Rich media extensibility 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. ]

Rich media apps incorporate data from the local folder or the web to provide a unique experience for viewing or editing the images they have captured. This topic describes how your app can incorporate rich media extensibility and extend the built-in photo viewer experience. Although a lens app can use rich media extensibility, rich media apps are not required to use lens extensibility. For more info about lenses, see Lenses for Windows Phone 8.

Note

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

To help make sure your app can be certified for the Windows Phone Store, review the rich media app certification requirements. For more info, see Additional requirements for specific app types for Windows Phone.

This topic contains the following sections.

Rich media app intro

A rich media app links photos stored in the media library to data stored in the local folder to create a unique in-app experience. For example, a social media app might combine the photo it captured and saved to the media library with data that it retrieves from a web service to create an experience that allows a user to view comments that their friends have posted about the photo. A slideshow app might allow the user to view a slideshow that the current photo is part of.

Although you’re limited to storing only JPG files in the media library, you can store additional information about the photo in your app’s local folder. To link the information, you can identify the photo by its path as returned by the GetPath extension method of the Picture class. To use GetPath, add a directive to Microsoft.Xna.Framework.Media.PhoneExtensions.

Don’t use the rich media open link for traditional photo editing, which is limited to only bit manipulations on the JPG file that’s in the camera roll. Rich media extensibility is intended for apps that do “rich editing” using additional information that it has about the photo. For example, allowing the user to choose a different photo from a “time shifted” capture, when additional photos are stored in the app’s local folder, would be considered rich editing. Use the open link only when the user can increase their experience of the photo by viewing it inside your app. For traditional photo editing, such as bit manipulations, cropping, brightening, rotating, etc., use the edit or apps link. The edit link is for Windows Phone 8 photo editing apps, and the apps link is for Windows Phone OS 7.1 photo editing apps.

Note

The open link appears only with the JPG files that a rich media app has saved in the media library. The edit and apps links appear with all JPG files saved in the media library.

Integrating your rich media app

When your rich media app saves a photo to the media library, the operating system “remembers” that your app captured it. That way, when you view the photo with the photo viewer, the photo viewer displays a captured by subtitle with the photo. In the app bar, the photo viewer presents a special open link specifically for launching your app. The following image shows the open link and the captured by caption.

The following steps describe how to integrate your rich media app into the photos experience.

Step 1: Specify capabilities

Windows Phone 8 apps need to specify the ID_CAP_MEDIALIB_PHOTO capability to access photos in the media library. Capabilities are specified in the app manifest file, WMAppManifest.xml.

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

Step 2: Register extensions

To declare that your app is a rich media app, register for the Photos_Rich_Media_Edit extension. Extensions are specified in the WMAppManifest.xml file. Just after the Tokens element, inside the Extensions element, the rich media extension is specified with the following Extension element.

<Extension ExtensionName="Photos_Rich_Media_Edit" 
           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 with the open link, 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 rich media launch when the URI contains the strings: RichMediaEdit and token. The following example is a launch URI for a rich media app (as seen from a URI mapper when the default navigation page is MainPage.xaml).

/MainPage.xaml?Action=RichMediaEdit&token=%7Bed8b7de8-6cf9-454e-afe4-abb60ef75160%7D

In this example, the token 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 open link 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 handle the photo referenced by the token, URI mapping may not be necessary.

However, if you want to launch a different page for a rich media experience, 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 rich media Open link.
            // Incoming URI example: /MainPage.xaml?Action=RichMediaEdit&token=%7Bed8b7de8-6cf9-454e-afe4-abb60ef75160%7D
            if ((tempUri.Contains("RichMediaEdit")) && (tempUri.Contains("token")))
            {
                // Redirect to RichMediaPage.xaml.
                mappedUri = tempUri.Replace("MainPage", "RichMediaPage");
                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 RichMediaPage.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 token parameter is used with the MediaLibraryGetPictureFromToken(String) method to extract the photo from the media library. This code is from the RichMediaEdit.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 "token" key is present.
    if (queryStrings.ContainsKey("token"))
    {
        // Retrieve the photo from the media library using the token passed to the app.
        MediaLibrary library = new MediaLibrary();
        Picture photoFromLibrary = library.GetPictureFromToken(queryStrings["token"]);

        // 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 access to the full-resolution image, use the PictureGetImage()()() method.

Testing rich media extensibility

This procedure describes how you can launch the Photo Extensibility Sample from the open link. This sample does not show an example of a rich media app, but it does show how to wire-up the extensibility for one.

To test rich media extensibility with the sample

Download the Photo Extensibility Sample and open it in the Windows Phone SDK.
Select Debug from the menu, and select Start Debugging.
On the main page of the app, tap the link: tap to prep for rich media testing.
On the photo save page, tap the capture and save button.
From the built-in photo app, take a photo by tapping on the screen, pressing the hardware shutter button, or if you are using the Windows Phone 8 Emulator, press F7.
Press accept after you capture the photo. When you do this, the built-in app automatically saves a photo to the media library. However, it is only the photo that your app saves to the library that will be shown with the captured by label. In the Photo Extensibility Sample, the photo-saving code is in the file PhotoSave.xaml.cs. The sample app saves a photo to the media library as soon as the built-in app returns.
After you capture the photo, tap Start to navigate to the Start screen.
On the Start screen, tap the Photos app and then select a photo that has been captured by the Photo Extensibility Sample 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 open link. This will launch a URI containing a token to the photo you were just viewing. That URI will ultimately launch the RichMediaEdit.xaml page and display the photo you were just looking at.