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
http://music.xbox.com 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:
The parameters type and Id are the only mandatory parameters to identify the content to point to.
|type||enum||Type of content being redirected to; see table of enumerations in this topic.|
|id||string||ID of the item. Parameter type depends on the value of the type parameter.|
|action||enum||Optional action to apply when opening the content. See the table below for possible values and corresponding actions.|
|target||enum||Optional 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.|
|Playlist||List of tracks and their metadata|
The action parameter is optional.Action parameter
|Value||Description||Fallback when not supported|
|view||Default. Launches the content details view.||Groove marketing page|
|play||Launches playback of the media content.||"view" experience|
|addtocollection||Opens the "add to collection" screen on the Groove service.||"view" experience|
|buy||Opens 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
|app||Force opening a rich application if available on the user's device.|
|web||Force opening the web client if supported on the user's web browser.|
|Entity||URL pattern||Example 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));