Export (0) Print
Expand All
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.
3 out of 6 rated this helpful - Rate this topic

How to handle URI activation (Windows Runtime apps using JavaScript and HTML)

Applies to Windows and Windows Phone

An app can register to become the default handler for a certain Uniform Resource Identifier (URI) scheme name. Both, desktop apps and Windows Store apps can register to be a default handler for a URI scheme name. If the user chooses your app as the default handler for a URI scheme name, your app will be activated every time that type of URI is launched.

We recommend that you only register for a URI scheme name if you expect to handle all URI launches for that type of URI scheme. If you do choose to register for a URI scheme name, you must provide the end user with the functionality that is expected when your app is activated for that URI scheme. For example, an app that registers for the mailto: URI scheme name should open to a new e-mail message so that the user can compose a new e-mail. For more info on URI associations, see Guidelines and checklist for file types and URIs.

These steps show how to register for a custom URI scheme name, alsdk://, and how to activate your app when the user launches a alsdk:// URI.

Instructions

Step 1: Specify the extension point in the package manifest

The app receives activation events only for the URI scheme names listed in the package manifest. Here's how you indicate that your app handles the alsdk URI scheme name.

  1. Double click to open package.appxmanifest in Solution Explorer.

    Here's a brief description of each of the fields that you may fill in the package manifest:

    FieldDescription

    Name

    Choose a name for a group of file types which share the same display name, logo, info tip, and edit flags. Choose a group name that can stay the same across app updates.

    Note  The Name must be in all lower case letters.

    Display Name

    Specify the display name to identify the URI scheme name in the Set Default Programs on the Control Panel.

    Logo

    Specify the logo that is used to identify the URI scheme name in the Set Default Programs on the Control Panel. If no logo is specified, the small logo for the app is used.

    Desired View (Windows-only)

    Specify the Desired View field to indicate the amount of space the app’s window needs when it is launched for the URI scheme name. The possible values for Desired View are Default, UseLess, UseHalf, UseMore, or UseMinimum.

    Note  Windows takes into account multiple different factors when determining the target app's final window size, for example, the preference of the source app, the number of apps on screen, the screen orientation, and so on. Setting Desired View doesn't guarantee a specific windowing behavior for the target app.

    Windows 8.1:  Desired View isn't supported until Windows 8.1 and Windows Server 2012 R2.

    Windows Phone:  Desired View isn't supported for Windows Phone.

     

  2. Select the Declarations tab.
  3. Select Protocol from the drop-down list and click Add.
  4. Enter alsdk as the Name.

    Important note:  Here is an alphabetic list of URI scheme names that you cannot enter into the package manifest because they are either reserved or forbidden: application.manifest, application.reference, batfile, blob, cerfile, chm.file, cmdfile, comfile, cplfile, dllfile, drvfile, exefile, explorer.assocactionid.burnselection, explorer.assocactionid.closesession, explorer.assocactionid.erasedisc, explorer.assocactionid.zipselection, explorer.assocprotocol.search-ms, explorer.burnselection, explorer.closesession, explorer.erasedisc, explorer.zipselection, file, fonfile, hlpfile, htafile, inffile , insfile, internetshortcut, jsefile, lnkfile, microsoft.powershellscript.1, ms-accountpictureprovider, ms-appdata, ms-appx, ms-autoplay, msi.package, msi.patch, ms-windows-store, ocxfile, piffile, regfile, scrfile, scriptletfile, shbfile, shcmdfile, shsfile,smb, sysfile, ttffile,unknown, usertileprovider,vbefile,vbsfile, windows.gadget,wsffile, wsfile,wshfile.

  5. Enter “images\Icon.png” as the Logo.
  6. Press Ctrl+S to save the change to package.appxmanifest.

This adds an Extension element like this one to the package manifest. The windows.protocol category indicates that the app handles the alsdk URI scheme name.



<Package xmlns="http://schemas.microsoft.com/appx/2010/manifest" xmlns:m2="http://schemas.microsoft.com/appx/2013/manifest">
   <Applications>
      <Application Id="AutoLaunch.App">
         <Extensions>
            <Extension Category="windows.protocol">
               <Protocol Name="alsdk"/>
               <Logo>images\logo.png</Logo>										
               <DisplayName>SDK Sample URI Scheme</DisplayName>
            </Extension>			            
         </Extensions>
      </Application>
   </Applications>
</Package>

Step 2: Add the proper icons

Apps that become the default for a URI scheme name have their icons displayed in various places throughout the system, for example, in the Default programs Control Panel.

We recommend that you include the proper icons with your project so that your logo looks great. Include in your image folder 16/32/48/256 pixel versions for the small logo and icon sizes. Match the look of the app tile logo with the color plate baked in. Test your icons on white backgrounds. For example icons, see the Association launching sample (Windows).

The Solution Explorer with a view of the files in the images folder. There are 16, 32, 48, and 256 pixel versions of both ‘Icon.targetsize’ and ‘smallTile-sdk’

Step 3: Register for the activated event

Register for the activated event to handle URI activation.


WinJS.Application.addEventListener("activated", onActivatedHandler, false);

Step 4: Handle the activated event

The activated event handler registered in step 1 receives all activation events. The kind property indicates the type of activation event. This example is set up to handle protocol activation events.


function onActivatedHandler(eventArgs) {
   if (eventArgs.detail.kind == Windows.ApplicationModel.Activation.ActivationKind.protocol) 
   {
       // TODO: Handle URI activation.

       // The received URI is eventArgs.detail.uri.rawUri
   }
}

Remarks

Any app or website can use your URI scheme name, including malicious ones. So any data that you get in the URI could come from an untrusted source. We recommend that you never perform a permanent action based on the parameters that you receive in the URI. For example, URI parameters could be used to launch the app to a user's account page, but we recommend that you never use them to directly modify the user's account.

Note  If you are creating a new URI scheme name for your app, be sure to follow the guidance in RFC 4395. This ensures that your name meets the standards for URI schemes.

  • Applies to Windows Phone

Note  

When launched via Protocol Contract, Windows Phone apps should make sure that Back button takes the user back to the screen that launched the app and not to the app's previous content.

It is recommended that apps create a new XAML Frame for each activation event that opens a new Uri target. This way, the navigation backstack for the new XAML Frame will not contain any previous content that the app might have on the current window when suspended.

Apps that decide to use a single XAML Frame for Launch and Protocol Contracts should clear the pages on the Frame's navigation journal before navigating to a new page. When launched via the Protocol Contract, apps should consider including UI that allows the user to go back to the top of the app.

Complete example

See Association launching sample (Windows).

Related topics

Concepts
Default Programs
File Type and URI Associations Model
Windows 8 Release Preview and Windows Server 2012 RC Compatibility Cookbook (User model information)
Tasks
How to launch the default app for a URI
How to handle file activation
Guidelines
Guidelines and checklist for file types and URIs
Reference
Windows.UI.WebUI.WebUIProtocolActivatedEventArgs
WinJS.Application.onactivated

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.