Guidelines for sharing content (Windows Store apps)

This topic describes best practices for sharing content between Windows Store apps.

User experience

When people swipe from the side of the screen and tap the share charm, the share pane appears with a list of apps people can share their content with. This list includes any apps that are “share targets” for a particular data format.

If your app has content to share, your app is a share source. If your app can receive content from other apps, then it’s a share target. Of course, apps can be both at once! Note: If your app is both source and target for a particular data format, then it appears by default in the list of share targets each time people share from your app. Sometimes this is great, and sometimes it’s a little silly to share with yourself. If it’s silly, then you should display an error message prompting the user to select a different target app. When people choose to share content, source apps provide the requested content in a shareable format, and display the metadata in the content preview. The chosen target app launches, reads the shared content, and displays whatever UI is appropriate.

When the target app reports that the sharing operation has completed, it can return a QuickLink to be displayed in the share window.

User experience with lengthy operations

Many sharing operations can take time to complete. People can start sharing a large amount of content and, while that is ongoing, switch to another app and check in on the progress of the share by re-opening the share window. If a sharing operation fails, Windows displays an informative message from the target app with steps to correct the problem when possible.

Best practices

We expect most, if not all, Windows Store apps apps to support some share tasks. Use the following best practices as you implement sharing in your app.

Source apps

When possible, include links to online versions of local content.

If an app supports downloading content that is also available to everyone on the web, it could share links to the online content rather than copies of the downloaded content. For example, suppose that a news site provides a rich reader app but also publishes the same articles on the website. If a user wants to share an article with a social networking site, the reader app can share links to the online version of the article that the user is currently viewing.

If you do not provide a website that enables everyone to view content, your app must share a copy of the content. For example, suppose that a photo viewing app does not have a corresponding website. The photo viewer can share the photos with a target app that can upload those to its own website.

Respect user selections

Your app can support content in multiple formats. It's important that your app respect the selection the user makes. For example, don't include a link to a webpage if the user has only selected a portion of that page.

Set properties and use them to supply useful information

When you package data for sharing, you have the option to supply a variety of properties that provide additional information about the content being shared. Take advantage of these properties to help the target apps improve the user experience. For example, providing a title and description that conveys what the user is sharing can help when the user is sharing content with more than one app. Adding a thumbnail when sharing an image or a link to a webpage can provide a visual reference to the user. For more information on what properties are available for you to use, check out our documentation on DataPackage.DataPackagePropertySet.

Provide a message to the user when sharing cannot be completed

If your app supports sharing but a particular sharing operation cannot be completed for some reason, provide a message to be displayed in the share window that describes the steps that the user must take to correct the problem.

Handling errors and other issues

In certain situations, your app might not be able to share. To help you handle these situations, the DataRequest object supports a FailWithDisplayText method. Use this method to display a text message when the user can't share from a particular view or needs to perform additional steps before sharing. For example, the app might require the user to select content for sharing but the user didn't select any.

Don't display a message that sharing is not supported by your app.

Windows will display a standard message to the user if your app does not support the sharing contract.

Don’t provide alternate ways to invoke sharing

Rely on the share charm and share window. Do not create a Share command on your app bar, or create a Share button in your app window or context menus.

Preserve user selections

Your app should preserve the user's selection even after the Share charm closes. This can help users if they want to modify their selection, or share the same content to multiple targets.

Provide a string that indicates what the user is sharing

You should provide a string that indicates what the user is sharing. For example, if the user is sharing a webpage, include a string that has the URL of the page. If it's an image, include a description if possible.

Support sharing of copied data

If your app supports a way to copy data in the app, you should also provide a way to share that same data.

Target apps

Keep the look and feel the same between your target app and your primary app.

Align your target app with the design for your primary app, including elements like fonts, colors, and controls. The target app should feel familiar to people who use your primary app frequently.

Keep interactions simple

Avoid time-consuming or complex interactions in your target app. In most cases, actions like text formatting, tagging people in photos, or setup tasks like connecting to a datasource, are best handled outside of the Share charm.

Keep navigation to a minimum

When a user selects your app to share content, Windows 8 automatically provides a back button for navigating back to the app list. You shouldn't depend on this back button—a target app can't use this button for its navigation. Also, avoid adding your own back button, or making your users navigate back and forth between multiple pages in your target app. Instead, use inline controls, such as progressive disclosure controls, select controls, and inline error messages.

Keep sign-in and setup interactions simple

If your setup and sign-in interactions are simple (one-step) you should let users complete those tasks through the Share charm so that users don't have to change context. You should avoid asking users to complete multi-step interactions through the Share charm. Instead, tell users to open your app directly to complete more complex interactions. When you use your main app (instead of the Share charm) to complete complex interactions you ensure that you have the space to organize those tasks clearly and effectively. If you are planning on using the web authentication broker for sign-in or sign-up interactions, see Web authentication broker.

Don't use light dismiss

The Share UI already uses light dismiss. Including another light dismiss element in your target app can cause confusion with your users.

Acknowledge user actions

When a user taps the Share charm or invokes the Share UI, let them know that the system is responding to their action—for example, through an inline message—before closing the share pane. This helps give the user confidence that their share started successfully.

Put important buttons where they can be easily reached

Put share buttons where users can reach them easily. We recommend putting share buttons on the right side of the screen, so users can reach them with their right thumbs.

Remove links that lead users away from the sharing experience

When a user is sharing content, you should take steps to ensure they remain in the sharing context. For example, if your app has links that lead to other areas of your app (such as to a home page), you should remove or hide them so the user doesn't leave the sharing experience accidentally.

Previews should match the actual content whenever possible

If your app includes a preview of what the user is sharing, that preview should match what will actually be shared as much as possible.

Use QuickLinks well

QuickLinks are links to your app that are customized for a specific set of user actions. Take advantage of these QuickLinks if there are specific actions (such as sending an email to a specific person), or there is a place (such as a photo album), that might save the user time and encourage them to share content with your app in the future.

Guidelines for debugging target apps

A share target app can be launched only through the Share charm, and clicking outside the app dismisses it. This means that most local debugging scenarios are impractical for share targets because clicking in the debugger will dismiss the target app.

To debug a share target app, you typically need to use the simulator or remote debugging because they operate on another machine, either virtually or physically.

For share target scenarios that can be debugged locally, remember that you can't close the target app after launching it from Visual Studio because the debugger will detach. Instead, leave the full-screen app open, go to the Start screen, and then perform your share scenario.

What to debug

A share target app is activated within a fraction of a second after launching, typically before you can attach a debugger to the running process. To debug code in the activation handler, it's best to debug directly on the local machine or through the simulator.

If you've implemented a long-running share, errors might occur after the app’s UI is dismissed. In this case, the debugger can remain attached to the target app even when the app is out of view. With the debugger attached, you can catch exceptions, pause on breakpoints, and walk through code without the app UI on screen.

Common issues

Unhandled exceptions in a target app cause it to immediately terminate and be replaced with an error message. The target app should gracefully handle any expected errors originating from the user, such as invalid input data, and report them to the user.

If a target app takes too long to respond to an activation event, the system assumes that the app is choosing not to respond and displays an error. Processing data should be moved out of the activation handler whenever possible, typically by storing a ShareOperation object and processing it asynchronously.

Calls to sharing the API can throw exceptions when called too many times or in the wrong order. When you implement a long-running share, be sure to call the share methods in the following order, without calling any single method twice in a row.

1. ReportStarted
2. ReportDataRetrieved
3. ReportSubmittedBackgroundTask

To learn more about the share API, see Windows.ApplicationModel.DataTransfer.ShareTarget namespace.

Related topics

Certification requirements

Build date: 12/5/2012