Export (0) Print
Expand All

Deep Link

Introduction

The Link property of every piece of content returned by content APIs is the key for third-party integration with Xbox Music applications: it contains a deep link that opens the piece of content on an Xbox Music client. These links exist and are used within Xbox Music applications for sharing the pages of artists, albums, and tracks. (See the table of examples in this topic.) They open native applications, such as the Windows 8.1 Music application, Windows Phone Marketplace, and the http://music.xbox.com web client, depending on the user's platform. If you're part of our affiliate program, refer to the Building an Affiliate Link section to learn how to build an affiliate link.

Deep links generated by the Xbox Music RESTful API will include an extra partnerId parameter for affiliate tracking.

The template of the redirect URL is as follows:

http://music.xbox.com/{type}/{Id}?action={action}&target={target}

The parameters type and Id are the only mandatory parameters to identify the content to point to.

ParameterTypeDescription
typeenumType of content being redirected to; see table of enumerations in this topic.
idstringID of the item. Parameter type depends on the value of the type parameter.
actionenumOptional action to apply when opening the content. See the table below for possible values and corresponding actions.
targetenumOptional choice of preferred target application. This parameter depends on a lot of different factors, so it is honored only as best-effort. See the table below for possible values and corresponding actions.
Type parameter list of possible values for deep links
ValueDescription
AlbumMusic album
ArtistMusic artist
PlaylistList of tracks and their metadata
TrackMusic song

The action parameter is optional.

Action parameter
ValueDescriptionFallback when not supported
viewDefault. Launches the content details view.Xbox Music marketing page
playLaunches playback of the media content."view" experience
addtocollectionOpens the "add to collection" screen on the Xbox Music service."view" experience
buyOpens the appropriate purchase flow on the Xbox Music service."view" experience

The target parameter is optional.

You can influence the behavior of the redirect by adding the target query parameter in the deep link. The redirect will try to honor that parameter if it makes sense and is possible. However, it is a best effort and might be overridden by our spec choices (for example, on Windows Phone 8, since the Xbox Music app is always installed, we will always try to redirect to it). You shouldn't assume this parameter will always be honored.

If the target parameter is not provided, the redirect will by default open the best available experience on the user's device.

Target parameter
ValueDescription
appForce opening a rich application if available on the user's device.
webForce opening the web client if supported on the user's web browser.
Examples
EntityURL patternExample URL
Artisthttp://music.xbox.com/Artist/xxxhttp://music.xbox.com/Artist/07070000-0200-11db-89ca-0019b92a3933
Albumhttp://music.xbox.com/Album/xxx?action=yyyhttp://music.xbox.com/Album/bcafef07-0100-11db-89ca-0019b92a3933?action=play
Trackhttp://music.xbox.com/Track/xxx?action=yyyhttp://music.xbox.com/Track/c1afef07-0100-11db-89ca-0019b92a3933?action=buy

App-to-app direct linking

To ensure the best experience and minimize redirection, you can start the Xbox Music application directly without going through a browser window. Just use the Link parameter you got from the API response in an invisibly instantiated WebView in your app. You can still use the action parameter in the Link to trigger a play—as described in Deep Link, for example.

Following are two code samples that demonstrate how:

Windows Store application

// In your xaml code, create a hidden WebView.
<WebView x:Name="HiddenWebView" Visibility="Collapsed" />

// Then when you receive the link, just use it in your WebView.
// On Windows 8, the user will be prompted with a popup saying that your app wants to open "Music", 
// and then it will open in full screen.
// On Windows 8.1, the user will have a popup as well, and then the Music app will open 
// with your app snapped on the side.
HiddenWebView.Source = new Uri(xboxMusicRedirectLink);

Windows Phone application

// In your xaml code, create a hidden WebBrowser control
<phone:WebBrowser x:Name="HiddenWebBrowser" />

// Then when you receive the link, just use it inside this control
HiddenWebBrowser.Navigate(new Uri(xboxMusicRedirectLink));

Community Additions

ADD
Show:
© 2014 Microsoft