Lens extensibility for Windows Phone 8
[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]
In Windows Phone 8, you can create a camera app called a lens. A lens opens from the built-in camera app and launches right into a viewfinder experience to help the user capture the moment. All lenses must register for a lens extension to appear in the lens picker. It’s the responsibility of your app to ensure that it opens to a viewfinder experience when it is launched from the lens picker. You also need to create new icons to use specifically for the lens picker. This topic describes how to incorporate lens extensibility into your app. For info about designing a lens app, see Lens design guidelines for Windows Phone.
Step 1: Prepare icons for the lens picker
The lens picker requires icons that are a different resolution than the app icon. Your app must provide three icons in the Assets folder, one for each of the three phone resolutions. For more info about these icons, see Lens design guidelines for Windows Phone.
Step 2: Register for a lens extension
To integrate with the lens experience, register for the Camera_Capture_App extension. This extension declares to the operating system that your app can display a viewfinder when it is launched from the lens picker. It also is used by the Windows Phone Store to identify lenses and display them in the lens picker. Extensions are specified in the WMAppManifest.xml file. Just after the Tokens element, inside the Extensions element, the lens extension is specified with the following Extension element.
<Extension ExtensionName="Camera_Capture_App"
ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5631}"
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: Handle a launch from the lens picker
It’s the responsibility of your app to ensure that it opens to a viewfinder experience when launched from the lens picker. When a user taps your app in the lens picker, a deep link URI is used to take the user to your app. You can either let the URI launch your default page (MainPage.xaml, for example) or use a URI mapper to launch a different page. This step describes both cases.
Launch your app to the default page
If you have only one page in your app and that page displays a viewfinder, no URI mapping is required. Your app launches to the page that is specified in the DefaultTask element of the app manifest file. Note that when you create a new Windows Phone app, MainPage.xaml is specified as the launch page by default.
Launch your app to a different page
If your default launch page doesn’t provide a viewfinder, use URI mapping to take the user to a page in your app that does have a viewfinder.
To map a launch from the lens picker to a specific page in your app, we recommend that you create your own URI mapper class based on the UriMapperBase class (in the System.Windows.Navigation namespace). In the URI mapper class, override the MapUri(Uri) method to map incoming URIs to pages in your app.
For example, the following code looks for a URI that contains the string ViewfinderLaunch. If the URI mapper finds the string, it takes the user to a page that displays a viewfinder named viewfinderExperience.xaml. If it doesn’t find that string, it returns the incoming URI in its original state.
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Windows.Navigation;
namespace LensExample
{
class LensExampleUriMapper : UriMapperBase
{
private string tempUri;
public override Uri MapUri(Uri uri)
{
tempUri = uri.ToString();
// Look for a URI from the lens picker.
if (tempUri.Contains("ViewfinderLaunch"))
{
// Launch as a lens, launch viewfinder screen.
return new Uri("/viewfinderExperience.xaml", UriKind.Relative);
}
// Otherwise perform normal launch.
return uri;
}
}
}
After you create a URI mapper class for your app, assign it to the frame of the app in the App.xaml.cs file. The following example shows how you can do this.
// Assign the lens example URI-mapper class to the application frame.
RootFrame.UriMapper = new LensExampleUriMapper();
This code assigns the LensExampleUriMapper class to the UriMapper property of the app frame. Don’t modify any of the existing code in the InitializePhoneApplication method; add only the UriMapper assignment, as shown in the following example.
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;
// Assign the lens example URI-mapper class to the application frame.
RootFrame.UriMapper = new LensExampleUriMapper();
// Handle navigation failures
RootFrame.NavigationFailed += RootFrame_NavigationFailed;
// Ensure we don't initialize again
phoneApplicationInitialized = true;
}
When the app is launched from the lens picker, it assigns the URI mapper during initialization. Before launching any pages, the app calls the MapUri method of the URI mapper to determine which page to launch. The URI that the URI mapper returns is the page that the app launches.
See Also
Other Resources
Photo extensibility for Windows Phone 8
Capturing photos for Windows Phone 8
Additional requirements for specific app types for Windows Phone
Lens design guidelines for Windows Phone