Guidelines for sharing content

Applies to Windows and Windows Phone

Let users to share content from your app or receive shared content from other installed apps with the Share contract. You can register your app as a share source, share target, or both. This topic describes best practices for sharing content between Windows Store apps.

If you'd like a more detailed overview of the sharing process, see Adding share (XAML) or Sharing and receiving content (HTML).

Examples

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 use to share their content. This list includes any installed apps that are “share targets” for a particular data format.

The links at the top of the image, called QuickLinks, allow users to complete specific share tasks directly. For example, when the user chose to share this content, QuickLinks appeared to let her email the URL to frequently used contacts, post it to the wall of her social media app, or add it to a specific page in a note-taking app. For reference, see the QuickLink class.

Share window

Here's the Share flyout that appears when the user chooses "Tweet@rama" from the list of share targets.

Share target app user interface

Lengthy share operations

Here's an example of a Share flyout completing lengthy share operations. Note the indeterminate progress bar and informative error message displayed by the target app when sharing failed. See the Guidelines for progress controls for more info.

Screen shots showing a progress notification in the share window

Dos and don'ts

Source apps

  • Share content in the format intended by the user. For example, if a user selects a portion of a webpage to share, don't share a link to the entire webpage. Instead share the selected text.
  • Provide a description that indicates what the user is sharing. For example, if the user is sharing a webpage, add a sentence that includes the URL of the page. If an image is being shared, include a description or title for the image.
  • If a user selects a portion of the displayed app content, preserve this selection after the Share flyout (window) closes. This helps users if they want to modify their selection, or share the same content with multiple targets.
  • Share links to online versions of local content rather than sharing a copy of local, downloaded content. For example, suppose a news site creates its own news app but also publishes the same articles on its website. If a user wants to share an article with a social networking site, the app should share links to the online version of the article that the user is currently viewing.
  • Inform the user when sharing can't be completed. If a particular sharing operation fails, display a message in the Share flyout that describes the problem and, if applicable, how the user can solve it. The DataRequest object supports a FailWithDisplayText method that is useful in this circumstance.
  • If your app supports a way to copy data in the app, you should also provide a way to share that same data.
  • Set properties to supply target apps with useful info about the content a user wants to share. See DataPackage.DataPackagePropertySet to learn about the available properties.
  • Don't display a message that sharing is not supported by your app. Windows displays a standard message for users if your app doesn't support the Share contract.

Target apps

  • Keep the look and feel the same between your target app and your primary app. The UI of your target app should feel familiar to people who use your primary app frequently. Keep fonts, colors, and controls consistent.
  • If your setup and sign-in processes only involve one step, let users complete those tasks through the Share charm so they don't have to change context.
  • 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. If it doesn't make sense for a user to share content using the same app, display an error message prompting the user to select a different target app.
  • Remove links that lead users away from the sharing experience. For example, if your target 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.
  • 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.
  • Take advantage of the QuickLink class. QuickLinks are links to your app that are customized for a specific set of user actions (like sending an email to a specific person). In the Examples section above, the links above the list of available target apps are QuickLinks.
  • Don't create a back button to navigate between pages in your target app. When a user selects your app to share content, Windows automatically provides a back button for navigating back to list of available target apps. Keep navigation simple in your target app using inline controls and error messages.
  • Don't perform time-consuming, complex, or multi-step interactions in your target app. Text formatting, tagging people in photos, or setup tasks like connecting to data sources are best handled outside of the Share charm. If your app requires multi-step sign-in or setup processes, tell users to open your app directly to complete more complex interactions.

Additional usage guidance

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 operation that can run even when a user navigates away from your app, 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 source 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 debugging 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. You can call ReportError or ReportCompleted at any time to complete the sharing operation.

Related topics

For designers
Charms and contracts
For developers (HTML)
ShareOperation
DataPackage
QuickLink
Sharing and receiving content (overview)
Quickstart: Sharing content
Quickstart: Receiving shared content
For developers (XAML)
ShareOperation
DataPackage
QuickLink
Adding share (overview)
Quickstart: Sharing content
Quickstart: Receiving shared content

 

 

Show:
© 2014 Microsoft