Deep Linking in Xbox One

This topic covers the concept of deep linking and explains how to provide support for it in your product. Apps and titles can use a deep link to launch another app or title, provided the target supports deep linking and the format is correct. There is no restriction placed on the launching app or the target. This also means that apps that run in the shared partition can launch games that run in the exclusive partition, and vice versa.

Introduction to Deep Linking

To understand deep linking, you need to be familiar with protocol activation. Two examples that most people are familiar with involve HTTP and mailto; after activating a link that uses either HTTP or mailto, most people expect a browser or an email program to open, either of which is a case of protocol activation. The browser and email programs are registered to respond when a URI with http: or mailto: is activated.

Deep linking is a technique that lets another product, or the shell, launch your product directly. When you create a deep link, you register your product to become the default handler for a specific URI scheme. Whenever the system executes that protocol, your product will respond to it. At its most basic level, deep linking launches or activates your product if it is already running, but you can also use deep linking to bypass the initial start screen or currently displayed activity of your product and proceed directly to a specific activity.

When a deep link is activated, it can contain arguments, and your product should respond to these arguments appropriately. One example is a link that specifies media content: If a user finds a specific video through a search and selects it, a deep link to the app that displays that content will also contain a string that identifies the specific video. The app should launch and handle playback of that video without any additional interaction from the user. (In this scenario, handling playback could mean playing the video or making it available for purchase.)

Tip

The arguments for a deep link are case-sensitive by default. To get around this complexity, you can use XboxJS.Navigation.parseProtocolActivation. This method parses the deep link arguments and is not case-sensitive.

How to implement deep linking in your product

There are two ways to implement deep links in your product on Xbox One:

Registered protocols

The first option for creating deep links is to use registered protocols. These are protocols that are customized for your product and are similar to HTTP and mailto, used in the example in the preceding section. When using registered protocols, you create your own custom protocol extension and register the specific protocol name in package.appxmanifest. Whenever that name is used in a URI, your product receives the activation message; so, you must create an event handler in your product for this activation message to respond to the deep link and any additional arguments that might be included. This form of deep linking is handled the same way as deep linking in Windows 8 apps. If you use registered protocols, you will be completely responsible for handling all of the protocol responses.

For more detailed information about supporting deep linking, see How to handle protocol activation (Microsoft Store apps using JavaScript and HTML).

When you do register for a specific URI scheme, you must be prepared to handle all activations of that URI. You also need to make sure that the name you use for your scheme is unique. You cannot have multiple products registering for the same scheme name. You should also make sure to follow the guidelines in RFC 4395 if you are creating a custom URI scheme name.

Important

A list of reserved or forbidden scheme names is provided in the MSDN topic How to handle protocol activation (Microsoft Store apps using JavaScript and HTML). In addition to that list, it is forbidden to use any protocol beginning with “ms-xbl”.

You can create custom arguments that are specific to your product and are known to your development team. You could use these arguments from other products to provide a form of interaction between products. You should not use deep linking arguments for passing messages back and forth, but you can use them to launch a product to a specific activity.

Title-based protocols

The second way to handle deep linking in your product involves a title-specific protocol. Every product that has a title ID specified in its AppXManifest is automatically registered in the shell to respond to a protocol tied to its title ID. This title-specific protocol has the following format:

ms-xbl-TitleID://authority?arg1=value1&arg2=value2…

The TitleID in the URI must be entered in lower case hexadecimal format. It also must be eight hexadecimal characters in length. If your TitleID is not eight characters long, you must pad the id with leading zeroes. The authority is required. Each URI can have a number of optional arguments. The maximum length for any URI is 2084 characters

For example, if your title ID was 123abcd, your product would be automatically registered for the following URI: ms-xbl-0123abcd://.

Note: When testing URI activation from the command line, place quotes around the entire URI or escape the ‘&’ (ampersand) by preceding it with a ‘^’ (caret). See Test Deep Links, below.

The following authorities are automatically supported for products:

default
Performs a default launch for the product. This is identical to if the user selected the tile for the product in the shell.

Deep linking to your Game Hub

Your game hub is a single destination on Xbox Live that has lots of information around your game. it’s where Xbox displays your game’s achievements, stats, leaderboard, game clips, your game’s activity feed and more.

From within your title or related companion app, you can link to your game hub to let Xbox take care of displaying these experiences related to your game.

To link to a game hub, use the following deep link format: xbox-gamehub:?titleId=12345

This will launch to the default page for your game hub (currently the Info tab). This format is consistent between Xbox One and Windows 10, so cross platform games can use the same deep link format on both platforms.

Optionally, go to a specific tab, you can use these:

Info tab
  This tab currently displays your game’s box art and description. It also has some quick action buttons to Follow, Launch, or Buy your game.   To launch to this tab: xbox-gamehub:info?titleId=12345

Activity Feed tab
  This tab currently displays your game’s activity feed and showcased feed item. Your activity feed is your way to reach out to your game’s players on Xbox Live. Your showcase is a special highlighted activity feed item for you to really call attention to an individual message.   To launch to this tab: xbox-gamehub:activityFeed?titleId=12345

Achievements tab
  This tab currently displays the user’s progress in your game’s achievements, hero stats, and hero stat leaderboards.   To launch to this tab: xbox-gamehub:achievements?titleId=12345

Friends tab
  This tab currently displays content related to your friends playing this game.

  1. A Joinable section highlighting if your friends are currently playing or broadcasting this game.
  2. A list of your friends who play this game.
  3. A list of popular broadcasters and game clip creators creating content around your game.

  To launch to this tab: xbox-gamehub:friends?titleId=12345

Captures tab
  This tab currently displays a list of trending game clips and screenshots the community is creating in your game.   To launch to this tab: xbox-gamehub:captures?titleId=12345

Media App Details

Media apps have some additional functionality and considerations when it comes to deep linking. This information applies specifically to title-based protocols. If you are using registered protocols, you are responsible for creating and handling all of the arguments.

Media apps might receive the following authorities as part of the URI in addition to those available to all products. Media apps are required to support some of these authorities.

media-details
  The app should launch to the page providing media details. Supporting this authority is required for media apps.

media-playback
  The app should launch to the page for media playback. Supporting this authority is required for media apps.

media-help
  The app should launch to its internal help page. One use of this could be for displaying help with login errors.

media-settings
  The app should launch to its internal settings page.

Media apps are also required to support the following query parameters that might be included as part of the optional arguments for a deep link. These are passed to the WinJS.Navigate.navigate function.

contentId
  The content id of the media that the app should play. This is provided in a string format. If this is not provided, your app will automatically navigate to the home page.

contentType
  The type of media that the app should play.

deepLinkInfo
  Application-specific data for your app.

You can use the XboxJS.Navigation.parseProtocolActivation method with media apps to provide support for title-based deep linking. This API will determine where your app should navigate in response to a deep link. It will not perform the actual navigation; you will need to provide that support in your app. The following pages are required and must be provided if you are using parseProtocolActivation:

Example

The following example adds the parseProtocolActivation method as a listener with pages specific to the app. When a deep link is received matching this app’s title ID, this sample will navigate to the provided pages.

var nav = WinJS.Navigation;

app.addEventListener("activated", function (args) {
    var protocolActivation = XboxJS.Navigation.parseProtocolActivation(args);

    if (protocolActivation || args.detail.kind === activation.ActivationKind.launch) {
        var navigationUri = nav.location,
            navigationOptions = nav.state;
        if (protocolActivation) {
            switch (protocolActivation.locationName) {
                case XboxJS.Navigation.LocationName.mediaHelpUri:
                    navigationUri = "/pages/help/help.html";
                    break;

                case XboxJS.Navigation.LocationName.mediaHomeUri:
                    navigationUri = "/pages/main/main.html";
                    break;

                case XboxJS.Navigation.LocationName.mediaDetailsUri:
                    navigationUri = "/pages/details/details.html";
                    break;

                case XboxJS.Navigation.LocationName.mediaPlaybackUri:
                    navigationUri = "/pages/playback/playback.html";
                    break;

                case XboxJS.Navigation.LocationName.mediaSettingsUri:
                    navigationUri = "/pages/settings/settings.html";
                    break;

                // Unhandled navigations should go to the main page.
                default:
                    navigationUri = "/pages/main/main.html";
                    break;
            }

            // Set the navigation options
            navigationOptions = protocolActivation.options;
        }

        // Now handle navigating to the appropriate page
        args.setPromise(WinJS.UI.processAll()
            .then(
                function () {
                    if (navigationUri) {
                        nav.history.current.initialPlaceholder = true;
                        return nav.navigate(navigationUri, navigationOptions);
                    } else {
                        return nav.navigate("/pages/main/main.html");
                    }
                }));
    }
});

Test Deep Links

There are two primary methods you can use to test deep links for your title.

See also

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

Passing Arguments to an App or Game