Content Linking Guide

This guide primarily covers content linking for mobile app developers working in the native environment, where it is possible to detect Spotify. If you are linking to Spotify content from the web, refer to the Web Links section below.

Best Experience: Open Spotify content in Spotify

On all major platforms (Android, iOS, MacOS, Windows), the Spotify app registers the spotify: URI scheme for handling deeplinks. These URIs are found in entities returned from the Spotify Web API under the uri field.

{
  "name": "She's So Unusual",
  "type": "album",
  ...
  "uri": "spotify:album:0sNOF9WDwhWunNAHPD3Baj"
}

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

Detecting Spotify from iOS Apps

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

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

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

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

Detecting Spotify from Android Apps

Use getPackageInfo on the PackageManager class to determine if Spotify is installed. The Spotify app for Android uses the package name com.spotify.music.

Example:

PackageManager pm = getPackageManager();
boolean isSpotifyInstalled;
try {
    pm.getPackageInfo("com.spotify.music", 0);
    isSpotifyInstalled = true;
} catch (PackageManager.NameNotFoundException e) {
    isSpotifyInstalled = false;
}

Opening Spotify Content in the Spotify App

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

iOS

Pass a Spotify web link to the openURL method of the UIApplication class to open the content in the Spotify app. 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:

NSURL *url = [NSURL URLWithString:@"https://open.spotify.com/album/0sNOF9WDwhWunNAHPD3Baj"];
[[UIApplication sharedApplication] openURL:url];

Android

Start an activity for an ACTION_VIEW Intent, passing your app’s package name in the EXTRA_REFERRER field.

Example:

Intent intent = new Intent(Intent.ACTION_VIEW);
intent.setData(Uri.parse("spotify:album:0sNOF9WDwhWunNAHPD3Baj"));
intent.putExtra(Intent.EXTRA_REFERRER,
                Uri.parse("android-app://" + context.getPackageName()));
startActivity(intent);

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 Adjust for mobile install attribution.

iOS

Trigger the Adjust tracker URL. Pass your application’s bundle ID in the campaign parameter. It is also important that you set the user agent to spotify_campaign_user_agent so the request is processed correctly:

NSString *adjustUrl = @"https://app.adjust.com/bdyga9?campaign=BUNDLE_ID";
NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:adjustUrl]];
[request setValue:@"spotify_campaign_user_agent" forHTTPHeaderField:@"User-Agent"];

[[[NSURLSession sharedSession] dataTaskWithRequest:request
                                 completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
}] resume];

Open Spotify in the App Store:

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

Android

Open Spotify in the Google Play Store, passing your application’s package name in the adjust_campaign parameter within the referrer:

final String appPackageName = "com.spotify.music";
final String referrer = "adjust_campaign=PACKAGE_NAME&adjust_tracker=ndjczk&utm_source=adjust_preinstall";

try {
    Uri uri = Uri.parse("market://details")
        .buildUpon()
        .appendQueryParameter("id", appPackageName)
        .appendQueryParameter("referrer", referrer)
        .build();
    startActivity(new Intent(Intent.ACTION_VIEW, uri));
} catch (android.content.ActivityNotFoundException ignored) {
    Uri uri = Uri.parse("https://play.google.com/store/apps/details")
        .buildUpon()
        .appendQueryParameter("id", appPackageName)
        .appendQueryParameter("referrer", referrer)
        .build();
    startActivity(new Intent(Intent.ACTION_VIEW, uri));
}

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.

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

Attribution

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

Allow Deeplinking from Webviews

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

Support deeplinks by ensuring the webview handles the following schemes:

• spotify:
• market: (Android)
• itms: (iOS)
• itms-apps: (iOS)

Read more: Android: https://stackoverflow.com/a/20134598 iOS: https://stackoverflow.com/a/4442594