Deep Link


The Link property of every piece of content returned by content APIs is the key for third-party integration with Groove applications: it contains a deep link that opens the piece of content on a Groove client. These links exist and are used within Groove 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 web client, depending on the user's platform.

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

The template of the redirect URL is as follows:{type}/{Id}?action={action}&target={target}

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

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
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.Groove marketing page
playLaunches playback of the media content."view" experience
addtocollectionOpens the "add to collection" screen on the Groove service."view" experience
buyOpens the appropriate purchase flow on the Groove 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 Groove 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
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.
EntityURL patternExample URL

App-to-app direct linking

To ensure the best experience and minimize redirection, you can start the Groove 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));