Share via

Quickstart: Receiving shared content (HTML)

  • Article

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

This quickstart walks you through the steps required to receive shared content from another app.

Objective: To learn how to receive shared content.

Prerequisites

To use the code described in this section:

  • You should be familiar with Visual Studio and its associated templates.
  • You should be familiar with JavaScript.

Instructions

1. Support the Share contract.

Before your app can receive shared content, you have to declare that it supports the Share contract. This contract lets the system know that your app is available to receive content. If you're using a Visual Studio template to create your app, here's how you support the Share contract:

  1. Open the manifest file. It should be called package.appxmanifest.
  2. Open the Declarations tab.
  3. Choose Share Target from the Available Declarations list.

To learn more, see Share Target Contract item template.

2. Specify the file types and data formats you support

As a target app developer, you need to decide what file types and data formats you want to support. To specify the file types you support:

  1. Open the manifest file.
  2. In the Supported File Types section of the Declarations page, click Add New.
  3. Type the file name extension that you want to support. For example, .docx. You need to include the period (.).

If you want to support all file types, check the SupportsAnyFileType box.

To specify the data formats you support:

  1. Open the manifest file.
  2. In the Data Formats section, click Add New.
  3. Type the name of the data format you support. For example, "Text".

The Share APIs support several standard formats, such as Text, HTML, and Bitmap. You can also specify custom file types and data formats. If you do, remember that source apps have to know what those types and formats are; otherwise, those apps won't share data of that type.

3. Handle share activation

When a user selects your app, an application activated event is fired. Your app needs to handle this event to process the data the user wants to share. Since there are many reasons that an activated event might be fired, the first thing you need to do is check whether the reason for the event is to share data.

if (eventObject.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.shareTarget) {
    // Code to handle activation goes here.
}

The data that the user wants to share is contained in a ShareOperation object. You can use this object to check the format of the data it contains. Here's an example of an event handler that handles shared content in plain text format:

var shareOperation = eventObject.detail.shareOperation;
if (shareOperation.data.contains(Windows.ApplicationModel.DataTransfer.StandardDataFormats.text)) {
    shareOperation.data.getTextAsync().done(function (text) {
            // To output the text using this example, 
            // you need a div tag with an id of "output" in your HTML file.
            document.getElementById("output").innerText = text;
        }, function (e) {
            displayError("Error retrieving Text format: " + e);
        }
    });
}

4. Report extended share status (for lengthy operations)

Note  

The following step applies only to Windows Store apps. You can call the reporting methods below from Windows Phone 8.1, but no data will be returned.

In some cases, it can take time for your app to process the data that the user wants to share. We call these share instances extended shares. Examples of extended shares include users sharing collections of files or images. These items are larger than a simple text string, so they take longer to process.

Note  If your app can only receive simple things like text or a hyperlink, you can skip this section.

 

As a target app, your app should not force the user to look at your app's UI just because it needs more time to handle data. Instead, you should use the ShareOperation object to let the system know that your app is still working. That way, the user can dismiss your app's UI and return to what they were doing. Meanwhile, your app continues to process the data in the background.

shareOperation.reportStarted();

After you call reportStarted, don't expect any more user interaction with your app. As a result, you shouldn't call it unless you're app is at a point where it can be dismissed by the user.

With an extended share, it's possible that the user might dismiss the source app before your app has all the data from the DataPackage object. As a result, we recommend that you let the system know when your app has acquired the data it needs. This way, the system can suspend or terminate the source app as necessary.

shareOperation.reportDataRetreived();

If something goes wrong, you can also call reportError to send an error message to the system. The user will see the message when they check on the status of the share. As soon as you call reportError your app is shut down and the share is ended—the user will need to start over to share the same content to your app. Depending on your scenario, you may decide that a particular error isn't serious enough to end the share operation. In that case, you can choose to not call reportError and to continue with the share.

shareOperation.reportError("Could not reach the server! Try again later.");

When you use these methods, you usually call them in the order just described, and you can't call them more than once. However, there are times when a target app can call reportDataRetrieved before reportStarted. For example, the app might retrieve the data as part of a task in the activation handler, but not call reportStarted until the user clicks a Share button.

To see this type of sharing in action, check out our Sharing content target app sample.

5. Report that sharing has been completed

Finally, when your app has successfully processed the shared content, you should call reportCompleted.

shareOperation.reportCompleted();

After your app reports that the share is complete, your app is dismissed.

Note  

QuickLinks are not supported in Windows Phone 8.1. Windows Phone Store apps can receive QuickLinks as part of a share operation, but they will be automatically ignored.

When a user selects your app to receive shared content, we highly recommend that you create a QuickLink. A QuickLink is like a shortcut that makes it easier for users to share information with your app. For example, your app could create a QuickLink that opens a new mail message pre-configured with a friend's email address.

When a user selects your app to receive shared content, we highly recommend that you create a QuickLink. A QuickLink is a shortcut that makes it easier for users to share information with your app. For example, your app could create a QuickLink that opens a new mail message pre-configured with a friend's email address.

A QuickLink must have a title, an icon, and an ID. The title (such as "Email Mom") and icon appear when the user taps the Share charm. The ID is what your app uses to identify which QuickLink was chosen. When your app creates a QuickLink, the app returns the QuickLink to the system by calling the ShareOperation object's reportCompleted method. Here's an example:

function reportCompleted() {
    var quickLink = new Windows.ApplicationModel.DataTransfer.ShareTarget.QuickLink();
    quickLink.id = "123456789";
    quickLink.title = id("quickLinkTitle").value;

    // For quicklinks, the supported FileTypes and DataFormats are set independently from the manifest.
    var dataFormats = Windows.ApplicationModel.DataTransfer.StandardDataFormats;
    quickLink.supportedFileTypes.replaceAll(["*"]);
    quickLink.supportedDataFormats.replaceAll([dataFormats.text, dataFormats.uri, dataFormats.bitmap, 
        dataFormats.storageItems, dataFormats.html, customFormatName]);

    Windows.ApplicationModel.Package.current.installedLocation.getFileAsync("images\\user.png").then(function (iconFile) {
        quickLink.thumbnail = Windows.Storage.Streams.RandomAccessStreamReference.createFromFile(iconFile);
        shareOperation.reportCompleted(quickLink);
    });
}

Remember that your app is responsible for storing the ID of the QuickLink and the corresponding user data. When the user taps the QuickLink, you can get its ID through the ShareOperation.quickLinkId property. When a share to a QuickLink is successful, you should return the same QuickLink when calling reportCompleted.

Summary and next steps

Now you should have a good idea how to received shared content, and how to create a QuickLink to help users share content with your app.

To learn more, or to get more specific examples of how to add sharing to your app, you might want to take a look at:

Note  Debugging a share target app is different from debugging other kinds of apps. To learn more, see Guidelines for debugging target apps.

 

Choosing data formats for sharing

Guidelines and checklist for sharing content

Quickstart: Sharing content