Extending the share picker for Windows Phone 8

Article
05/20/2016

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

This topic describes how your app can appear in the share picker, a page that lets the user pick an app for sharing the photo they are viewing. Learn about how your app can access that photo without asking the user to select it. Note that this extensibility is only available when the photo is a JPG file. For more info about other ways you can extend the photos experience, see Photo extensibility for Windows Phone 8.

Note

Much of the code featured in this topic is from the Photo Extensibility Sample.

This feature is for apps that share photos to a web service. To help make sure your app can be certified for the Windows Phone Store, see Additional requirements for specific app types for Windows Phone.

This topic contains the following sections.

The share picker appears in the built-in photo viewer. You launch it from the app bar, by tapping on the share link. Also, starting in Windows Phone 8, other apps can launch the share picker too. For more info, see How to use the share media task for Windows Phone 8.

The following image shows the photo viewer share link and the name of the share picker extension (which is described later in this topic).

The following steps describe how to integrate your app into the share picker.

Step 1: Specify capabilities

Specify a media library capability to access photos in the media library. Capabilities are specified in the app manifest file, WMAppManifest.xml.

For Windows Phone 8 apps, use the ID_CAP_MEDIALIB_PHOTO capability.

<!-- For accessing photos in the media library. -->
<Capability Name="ID_CAP_MEDIALIB_PHOTO" />

For Windows Phone OS 7.1 apps, use the ID_CAP_MEDIALIB capability.

<!-- For accessing photos in the media library. -->
<Capability Name="ID_CAP_MEDIALIB" />

Step 2: Register extensions

To appear in the share picker, register for the Photos_Extra_Share extension. Extensions are specified in WMAppManifest.xml. Just after the Tokens element, inside the Extensions element, the share picker extension is specified with the following Extension element.

<Extension ExtensionName="Photos_Extra_Share" 
           ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5632}" 
           TaskID="_default" />

The Windows Phone Manifest Designer does not support extensions; use the XML (Text) Editor to edit them. For more info, see How to modify the app manifest file for Windows Phone 8.

Step 3: Map the launch URI

When the user taps your app in the share picker, a deep link URI is launched to open your app and send a token to the photo that the user was viewing. Your app can detect a share picker launch when the URI contains the strings: ShareContent and FileId. The following example is a launch URI from the share picker (as seen from a URI mapper when the default navigation page is MainPage.xaml).

/MainPage.xaml?Action=ShareContent&FileId=%7BA3D54E2D-7977-4E2B-B92D-3EB126E5D168%7D

In this example, the FileId parameter value is the token. That string can be used to retrieve the photo from the media library. This is described later in the topic.

Because the share picker targets the default navigation page (in this case, MainPage.xaml), that page will be launched if you don’t implement any URI mapping. If your app’s default navigation page can share the photo referenced by the token, URI mapping may not be necessary.

However, if you want to launch a different page for sharing a photo, you’ll need to map the URI to that page. The following example shows how this is done with a custom URI mapper class.

using System;
using System.Windows.Navigation;

namespace CustomMapping
{
    class CustomUriMapper : UriMapperBase
    {
        public override Uri MapUri(Uri uri)
        {
            string tempUri = uri.ToString();
            string mappedUri;

            // Launch from the photo share picker.
            // Incoming URI example: /MainPage.xaml?Action=ShareContent&FileId=%7BA3D54E2D-7977-4E2B-B92D-3EB126E5D168%7D
            if ((tempUri.Contains("ShareContent")) && (tempUri.Contains("FileId")))
            {
                // Redirect to PhotoShare.xaml.
                mappedUri = tempUri.Replace("MainPage", "PhotoShare");
                return new Uri(mappedUri, UriKind.Relative);
            }

            // Otherwise perform normal launch.
            return uri;
        }
    }
}

In this example, the URI mapper maps the incoming URI to a page named PhotoShare.xaml by replacing the page name within the URI. The URI returned by that method is then used by the root frame of the app to launch the first page when the app starts. The root frame uses the custom URI mapper because it is assigned as the app initializes. The following code shows how the URI mapper is assigned in the InitializePhoneApplication method of the App.xaml.cs file.

private void InitializePhoneApplication()
{
    if (phoneApplicationInitialized)
        return;

    // Create the frame but don't set it as RootVisual yet; this allows the splash
    // screen to remain active until the application is ready to render.
    RootFrame = new PhoneApplicationFrame();
    RootFrame.Navigated += CompleteInitializePhoneApplication;

    // Handle navigation failures
    RootFrame.NavigationFailed += RootFrame_NavigationFailed;

    // Assign the custom URI mapper class to the application frame.
    RootFrame.UriMapper = new CustomMapping.CustomUriMapper();

    // Ensure we don't initialize again
    phoneApplicationInitialized = true;
}

Step 4: Handle the URI Parameters

When the page is launched, the page can access all of the parameters in the URI (that launched the page) using the QueryString property of the page’s NavigationContext object. The following example shows how the value of the FileId parameter is used with the MediaLibraryGetPictureFromToken(String) method to extract the photo from the media library. This code is from the PhotoShare.xaml.cs file of the Photo Extensibility Sample.

protected override void OnNavigatedTo(NavigationEventArgs e)
{
    // Get a dictionary of query string keys and values.
    IDictionary<string, string> queryStrings = this.NavigationContext.QueryString;

    // Ensure that there is at least one key in the query string, and check whether the "FileId" key is present.
    if (queryStrings.ContainsKey("FileId"))
    {
        // Retrieve the photo from the media library using the FileID passed to the app.
        MediaLibrary library = new MediaLibrary();
        Picture photoFromLibrary = library.GetPictureFromToken(queryStrings["FileId"]);

        // Create a BitmapImage object and add set it as the image control source.
        // To retrieve a full-resolution image, use the GetImage() method instead.
        BitmapImage bitmapFromPhoto = new BitmapImage();
        bitmapFromPhoto.SetSource(photoFromLibrary.GetPreviewImage());
        image1.Source = bitmapFromPhoto;
    }
}

This example uses an extension method of the Picture class, PhoneExtensionsGetPreviewImage()()(). This method returns a large thumbnail in a resolution that has been optimized to fill the screen of the phone (WVGA, WXGA, or 720p). If you want to share the full-resolution image, use the PictureGetImage()()() method.

This procedure describes how you can launch your app from the share picker. If you are testing on the Windows Phone 8 Emulator, you can skip the procedure for preparing your phone.

Note

When debugging Windows Phone OS 7.1 apps, keep in mind that re-launching your app will break the debugging process on your first app instance. Also, Emulator 7.1 does not support photo extensibility testing: that emulator does not contain a Photos Hub.

To prepare your phone for testing

If you are testing extensibility with the Windows Phone 8 Emulator, you can skip this procedure and move on to the next procedure. If you are testing with your phone, continue on.
Confirm that you have photos on your phone or take a picture with the Windows Phone camera.
Tether it to your computer and wait for it to be recognized.
(This step is for Windows Phone OS 7.1 only) Run the WPConnect.exe tool as described in How to test apps that use the photo chooser or camera capture task for Windows Phone 8. This tool disconnects the Zune software from the media database on your phone. WPConnect.exe allows you to use the Photos Hub while your phone is tethered to your computer.

Select Debug from the menu, and select Start Debugging.
Tap Start to navigate to the Start screen.
On the Start screen, tap the Photos app and then select a photo and view it in the photo viewer.
Tap the three dots at the bottom of the page on the app bar. When the app bar expands, tap the share link.
On the SHARE page, tap on your app to launch it. This will launch a URI containing a token to the photo you were just viewing. If you are testing with the Photo Extensibility Sample, it will launch the PhotoShare.xaml page and display the photo you were just looking at.

Extending the share picker for Windows Phone 8