Skip to content

iOS Content Linking

This tutorial covers content linking for iOS devices, where it is possible to detect Spotify.

The Spotify app registers the spotify: URI scheme to handle deeplinks. These URIs are found in entities returned from the Spotify Web API under the uri field. For example, the get album endpoint returns:


_10
{
_10
"name": "This Is All Yours",
_10
"release_date": "2014-09-22",
_10
"release_date_precision": "day",
_10
"type": "album",
_10
"uri": "spotify:album:4oktVvRuO1In9B7Hz0xm0a"
_10
}

When Spotify is installed, navigating directly to content in the Spotify app provides the best user experience, since it brings Spotify to the foreground with the selected content. However, you must first determine whether Spotify is present on the device.

Detecting Spotify

Your app must declare its intent to detect Spotify. Add spotify under the LSApplicationQueriesSchemes key in your project’s Info.plist:


_13
<?xml version="1.0" encoding="UTF-8"?>
_13
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
_13
<plist version="1.0">
_13
<dict>
_13
...
_13
<key>LSApplicationQueriesSchemes</key>
_13
<array>
_13
<string>spotify</string>
_13
...
_13
</array>
_13
...
_13
</dict>
_13
</plist>

Pass a Spotify URI to canOpenURL on the UIApplication class to determine if Spotify is installed:


_10
[[UIApplication sharedApplication] canOpenURL:[NSURL URLWithString:@"spotify:"]]

Opening Spotify content in the Spotify app

Once you've determined Spotify is installed, you can navigate directly to Spotify deeplinks.

Pass a Spotify web link to the openURL method of the UIApplication class to open the content in the Spotify app. Start with passing your app’s Bundle ID in the ~campaign parameter. Append the Spotify Content link to the ~$canonical_url parameter to ensure proper routing and user experience. A web link is preferred over a spotify: deeplink in this scenario because a deeplink will trigger an iOS confirmation prompt before switching to Spotify. Spotify handles the web link through the Universal Links mechanism.

Example:


_10
_10
NSString *bundleId = [[NSBundle mainBundle] bundleIdentifier];
_10
NSString *canonicalURL = @"https://open.spotify.com/album/0sNOF9WDwhWunNAHPD3Baj";
_10
NSString *branchLink = [NSString stringWithFormat:@"https://spotify.link/content_linking?~campaign=%@&$canonical_url=%@", bundleId, canonicalURL];
_10
_10
NSURL *url = [NSURL URLWithString:branchLink];
_10
_10
[[UIApplication sharedApplication] openURL:url];

Installing Spotify

Follow the steps below if you wish to link users directly to the app store so that they can install Spotify. Spotify partners with Branch for mobile install attribution.

Trigger the Branch tracker URL. Pass your application’s bundle ID in the ~campaign parameter. You can optionally append the Spotify Content link through the ~$canonical_url parameter to support deferred deep linking.


_10
NSString *bundleId = [[NSBundle mainBundle] bundleIdentifier];
_10
NSString *canonicalURL = @"https://open.spotify.com/album/0sNOF9WDwhWunNAHPD3Baj";
_10
NSString *branchLink = [NSString stringWithFormat:@"https://spotify.link/content_linking?~campaign=%@&$canonical_url=%@", bundleId, canonicalURL];
_10
NSURLRequest *request = [[NSURLRequest alloc] initWithURL:[NSURL URLWithString:branchLink]];
_10
_10
[[[NSURLSession sharedSession] dataTaskWithRequest:request
_10
completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
_10
}] resume];

Open Spotify in the App Store:


_10
NSString *url = @"https://itunes.apple.com/app/spotify-music/id324684580?mt=8";
_10
[[UIApplication sharedApplication] openURL:[NSURL URLWithString:url]];

Fallback experience: Web Links

If the user doesn’t have Spotify installed or you’re otherwise unable to detect Spotify, you should open Spotify web links (open.spotify.com) in the system browser or a webview.

Web links are provided in Web API entities under the external_urls.spotify field.


_10
{
_10
"name": "She's So Unusual",
_10
"type": "album",
_10
...
_10
"external_urls" : {
_10
"spotify" : "https://open.spotify.com/album/0sNOF9WDwhWunNAHPD3Baj"
_10
}
_10
}

Attribution

In order for Spotify to attribute traffic to your app, pass your application's bundle ID in the utm_campaign query string parameter. For example: https://open.spotify.com/track/55fmthmn3rgnk9Wyx7G5dU?utm_campaign=com.app

Info:Web links from the Web API may contain other query string parameters. Make sure your implementation preserves existing parameters

Allow deeplinking from Webviews

Content at open.spotify.com links directly into Spotify or the app store. By default, iOS restricts webviews and prevent deeplinking into apps.

Support deeplinks by ensuring the webview handles the following schemes:

  • spotify:
  • itms:
  • itms-apps:

Further read

iOS: https://stackoverflow.com/a/4442594