How to share a link (HTML)

Article
10/13/2015

[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]

Links, or Uniform Resource Identifiers (URIs), are another common data format that users want to share. The most common reason to share a link is when a user has specifically selected one; however, we also recommend that your app support sharing links:

When the content the user selects is also available online.
As a secondary source when sharing HTML.

What you need to know

Technologies

Windows.ApplicationModel.DataTransfer

Prerequisites

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

Instructions

Step 1: Get the DataTransferManager object

The DataTransferManager object is the starting point for any sharing operation.

var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
    dataTransferManager.addEventListener("datarequested", shareAsyncHandler);

Step 2: Add an event handler for the datarequested event

Add a DataRequested event handler to fire when the user wants to invoke Share. In a Windows Store app, this occurs automatically when the user invokes the Share charm. If you're developing for Windows Phone, there is no built-in Share charm, so you'll need to add a control for the user to tap and trigger the handler.

dataTransferManager.addEventListener("datarequested", function (e) {
    // Code to handle event goes here.
});

Step 3: Get a DataRequest object

When a datarequested event occurs, your app receives a DataRequest object. This object contains a DataPackage that you can use to provide the content that the user wants to share.

var request = e.request;

Step 4: Add the link to the DataPackage

To add the link, use the setUri method.

request.data.setUri(new Windows.Foundation.Uri("http://www.fabrikam.com"));

Remarks

For apps that share an activation protocol URI, add some additional information to the DataPackage besides the URI. This helps ensure that target apps can provide a better experience to all users, including those using a different operating system (OS).

Provide a good title and description for the content.
Include an HTML snippet that describes the content being shared, and includes the URI inline. We recommend including a string that emphasizes that the link works for Windows 8 users and, if possible, provide an additional web link for users on a different operating system (OS).
Include a text version of your HTML snippet.

Some target apps might register to support URIs even if they can really only handle http:// or https:// URIs. Providing alternative data formats makes it more likely that the target app will successfully complete your scenario.

Complete example

Here's an example of a function that sets a link for a user to share. For a more complete example, check out our code gallery sample.

function registerForShare() {
    var dataTransferManager = Windows.ApplicationModel.DataTransfer.DataTransferManager.getForCurrentView();
    dataTransferManager.addEventListener("datarequested", shareLinkHandler);
}

function shareLinkHandler(e) {
        var request = e.request;
        request.data.properties.title = "Share Link Example";
        request.data.properties.description = "A demonstration that shows how to add a link (URI) to share.";
        request.data.setUri(new Windows.Foundation.Uri("http://www.fabrikam.com"));
}