How to handle protocol activation (Windows Store apps using JavaScript and HTML)

Windows allows an app to register to become the default handler for a certain URI scheme name. Both desktop 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.

You should 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 it is important that you 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 file associations see Guidelines and checklist for file types and URIs.

The following steps will show you how to register for a custom URI scheme name, alsdk://, and how your app can be activated 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 is a brief description of each of the fields that you may fill in the above form:

   Field	Description
   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.

    

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">
   <Applications>
      <Application Id="AutoLaunch.App">
         <Extensions>
            <Extension Category="windows.protocol">
               <Protocol Name="alsdk" />
               <Logo>images\logo.png</Logo>										
               <DisplayName>SDK Sample Protocol</DisplayName>
            </Extension>			            
         </Extensions>
      </Application>
   </Applications>
</Package>

Step 2: Add the proper icons

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

It’s important that you include the proper icons with your project so that your logo looks great. You should include in your image folder 16/32/48/256 px small logo and icon sizes . These icons should match the look of the app tile logo with the color plate baked in. You should test your icons on white backgrounds. See the Association launching sample for example icons.

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 protocol activation.

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

Remarks

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

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

Note  

Complete example

See Association launching sample.

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

Build date: 10/26/2012