This tutorial leads you step-by-step through the creation of a simple app that uses the Spotify App Remote to play an audio track and subscribe to player state. Within the download package you will also find a demo app with full source code to help get you started.

If you are using Swift please see the Swift Quick Start

Please note: the Spotify App Remote SDK (iOS) is currently a beta release; its content and functionality is likely to change significantly without warning. Note that by using Spotify developer tools, you accept our Developer Terms of Use.

You can read more about the App Remote SDK in the overview, or dig into the reference documentation.

Prepare Your Environment

Follow these steps to make sure you are prepared to start coding.

Register Your App

You will need to register your application on the Developer Dashboard and obtain a client ID. When you register your app you will also need to register a redirect URI that the Spotify Accounts Service will use to callback to your app after authorization. You also should add your bundle id as it is used to verify the identity of your application.

Install Spotify App

Install the latest version of Spotify from Apple’s App Store on the device you want to use for development. Run the Spotify app and login or sign up. Note: You must use a physical device to test App Remote as Spotify cannot be installed on your simulator. For instructions on how to install apps to devices see Apple’s documentation.

Download the SDK

Download the Spotify App Remote SDK from our GitHub.

Add Dependencies

1) Add the SpotifyAppRemote.framework to your project by first copying the framework into the directory of your Xcode project. Then in Xcode select your top level Xcode project in the Project Navigator. Select your target, go to “Build Phases” and tap “+” under “Link Binary With Libraries”.

Navigate to Link Binary With Libraries

Choose “Add Other” and find the SpotifyAppRemote.framework you downloaded and copied into your project folder.

Choose "Add Other"

Ensure that your framework is now showing up in your Project Navigator.

Import SpotifyAppRemote.framework

2) Add -ObjC to your project’s “Other Linker Flags” (Technical Q&A QA1490)

Other Linker Flags

3) Set “Enable Bitcode” to No under Build Options

Disable Bitcode

4) In your info.plist add your redirect URI you registered at My Applications. You will need to add your redirect URI under “URL types” and “URL Schemes”. Be sure to set a unique “URL identifier” as well. This redirect URI is how the Spotify app will open your app after the authorization process. More info on URL Schemes

Info.plist

5) Add #import <SpotifyAppRemote/SpotifyAppRemote.h> to your source files to import necessary headers.

Authorize Your Application

To be able to use App Remote the user needs to authorize your application. If they haven’t, the connection will fail with a No token provided error. To allow the user to authorize your app, you can use the Single Sign-On flow described in the iOS SDK Tutorial. This approach can be useful if your application needs a token with multiple scopes. If you’re only interested in using App Remote you can use the built-in authorization flow.

Using the built-in Authorization flow

First add a property to retain your SPTAppRemote object and conform to SPTAppRemoteDelegate and SPTAppRemotePlayerStateDelegate (added to the AppDelegate in this example)

@interface AppDelegate () <SPTAppRemoteDelegate, SPTAppRemotePlayerStateDelegate>
@property (nonatomic, strong) SPTAppRemote *appRemote;
@end

Then initialize SPTAppRemoteConnectionParams with your client ID and redirect URI, and use them to initialize the SPTAppRemote. In this example we are initializing App Remote in application:didFinishLaunchingWithOptions: in our AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  SPTAppRemoteConnectionParamsImageFormat format = SPTAppRemoteConnectionParamsImageFormatAny;
  SPTAppRemoteConnectionParams *params =
    [[SPTAppRemoteConnectionParams alloc] initWithClientIdentifier:@"your_client_id"
                                                       redirectURI:@"your_redirect_uri"
                                                              name:@"your_app_name"
                                                       accessToken:nil
                                                  defaultImageSize:CGSizeZero
                                                       imageFormat:format];

  self.appRemote = [[SPTAppRemote alloc] initWithConnectionParameters:params
                                            logLevel:SPTAppRemoteLogLevelDebug];
  self.appRemote.delegate = self;

  return YES;
}

Initiate the authentication flow. Note: If a song is already playing when initiating the authentication flow, it will resume playing instead of playing the new URI.

// Note: A blank string will play the user's last song
NSString *uri = @"spotify:track:69bp2EbF7Q2rqc5N3ylezZ";
BOOL spotifyInstalled = [self.appRemote authorizeAndPlayURI:uri];
if (!spotifyInstalled) {
    /*
     * The Spotify app is not installed.
     * Use SKStoreProductViewController with [SPTAppRemote spotifyItunesItemIdentifier]
     * to present the user with a way to install the Spotify app.
     */
}

Lastly configure your AppDelegate to parse out the accessToken in application:openURL:options: and set it on the SPTAppRemote connectionParameters

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    NSDictionary *params = [self.appRemote authorizationParametersFromURL:url];
    NSString *token = params[SPTAppRemoteAccessTokenKey];
    if (token) {
        self.appRemote.connectionParameters.accessToken = token;
    } else if (params[SPTAppRemoteErrorDescriptionKey]) {
        NSLog(@"%@", params[SPTAppRemoteErrorDescriptionKey]);
    }
    return YES;
}

Connect and Subscribe to Player State

Once you have an auth token you can attempt to connect. See our Application Lifecycle Guide for more on when to connect and disconnect, and how to manage auth tokens.

[self.appRemote connect];

Add SPTAppRemoteDelegate callbacks to monitor connection state

- (void)appRemoteDidEstablishConnection:(SPTAppRemote *)appRemote
{
    // Connection was successful, you can begin issuing commands
}

- (void)appRemote:(SPTAppRemote *)appRemote didFailConnectionAttemptWithError:(NSError *)error
{
    // Connection failed
}

- (void)appRemote:(SPTAppRemote *)appRemote didDisconnectWithError:(nullable NSError *)error
{
    // Connection disconnected
}

Then add the SPTAppRemotePlayerStateDelegate callback method

- (void)playerStateDidChange:(id<SPTAppRemotePlayerState>)playerState
{
    NSLog(@"Track name: %@", playerState.track.name);
}

And lastly set the playerAPI delegate and subscribe to player state once a connection has been established

- (void)appRemoteDidEstablishConnection:(SPTAppRemote *)appRemote
{
    // Connection was successful, you can begin issuing commands

    appRemote.playerAPI.delegate = self;
    [appRemote.playerAPI subscribeToPlayerState:
      ^(id  _Nullable result, NSError * _Nullable error) {
        if (error) {
            NSLog(@"%@", error.localizedDescription);
        }
    }];
}

You can view the final AppDelegate code for this example here

Next Steps

Congratulations! You’ve interacted with the App Remote SDK for the first time. Time to celebrate, you did a great job! 👏

Want more? Here’s what you can do next:

  • Learn about how the App Remote SDK interacts with the iOS application lifecycle in our guide.
  • Dive into other things you can do with the SDK in the App Remote SDK Reference.
  • Be sure to check out the sample code in the Demo Projects folder included with the SDK.