iOS SDK Quick Start

Welcome! In this Quick Start, we will go through how to use the Spotify iOS SDK in your existing Xcode application to integrate:

• Authentication (via the Spotify Accounts API) 🔒
• Shuffle playback for Spotify Free users 🔈
• On-demand playback for Spotify Premium users 🔈
• Real-time player state updates 👂

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

Prepare Your Environment

Setup the iOS SDK

At this point, we should have the following:

• A registered Client ID
• A downloaded copy of the Spotify iOS SDK
• The latest version of the Spotify app installed on an iOS device

Next we’ll focus on installing the SDK inside of an existing Xcode application.

<key>LSApplicationQueriesSchemes</key>
<array>
  <string>spotify</string>
</array>

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>com.spotify.iOS-SDK-Quick-Start</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>spotify-ios-quick-start</string>
    </array>
  </dict>
</array>

#import <SpotifyiOS/SpotifyiOS.h>

Set Up User Authorization

In order for the iOS SDK to control the Spotify app, they will need to authorize your app. If you need to authorize for more scopes than just controlling Spotify with App Remote please take a look at advanced auth otherwise please read on.

Instantiate SPTConfiguration

At a class-level, we can define our Client ID, Redirect URI and instantiate the SDK:

let SpotifyClientID = "[your spotify client id here]"
let SpotifyRedirectURL = URL(string: "spotify-ios-quick-start://spotify-login-callback")!

lazy var configuration = SPTConfiguration(
  clientID: SpotifyClientID,
  redirectURL: SpotifyRedirectURL
)

Configure Auth Callback

Once a user successfully returns to your application, we’ll need to the access token to the App Remote

func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
  let parameters = appRemote.authorizationParameters(from: url);

        if let access_token = parameters?[SPTAppRemoteAccessTokenKey] {
            appRemote.connectionParameters.accessToken = access_token
            self.accessToken = access_token
        } else if let error_description = parameters?[SPTAppRemoteErrorDescriptionKey] {
            // Show the error
        }
  return true
}

If you are using UIScene then you need to use appropriate method in your scene delegate.

func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else {
        return
    }

    let parameters = appRemote.authorizationParameters(from: url);

    if let access_token = parameters?[SPTAppRemoteAccessTokenKey] {
        appRemote.connectionParameters.accessToken = access_token
        self.accessToken = access_token
    } else if let error_description = parameters?[SPTAppRemoteErrorDescriptionKey] {
        // Show the error
    }
}

User authorization provides offline support. This means that a user can be authorized even if the device is currently offline. Offline support works out of the box, so it doesn’t require any additional implementation.

To successfully authorize a user while offline, the following conditions have to be met:

• Your application has successfully connected to Spotify within the last 24 hours
• Your application uses the same redirect URI, client ID and scopes when connecting to Spotify

Setup App Remote

With authentication implemented, we can now control the Spotify main application to play music and notify us on playback state:

Implement Remote Delegates

We’ll need to implement two delegates: SPTAppRemoteDelegate and SPTAppRemotePlayerStateDelegate. These will respectively provide connection and playback state methods to implement inside of our AppDelegate.swift:

class AppDelegate: UIResponder, UIApplicationDelegate, SPTAppRemoteDelegate, SPTAppRemotePlayerStateDelegate {
  ...

or if you are using UIScene:

class SceneDelegate: UIResponder, UIWindowSceneDelegate, SPTAppRemoteDelegate, SPTAppRemotePlayerStateDelegate
  ...

These will require us to implement the following methods:

func appRemoteDidEstablishConnection(_ appRemote: SPTAppRemote) {
  print("connected")
}
func appRemote(_ appRemote: SPTAppRemote, didDisconnectWithError error: Error?) {
  print("disconnected")
}
func appRemote(_ appRemote: SPTAppRemote, didFailConnectionAttemptWithError error: Error?) {
  print("failed")
}
func playerStateDidChange(_ playerState: SPTAppRemotePlayerState) {
  print("player state changed")
}

Initialize App Remote

We’ll next need to initialize App Remote on a class-level closure, which can take the self.configuration we defined earlier:

lazy var appRemote: SPTAppRemote = {
  let appRemote = SPTAppRemote(configuration: self.configuration, logLevel: .debug)
  appRemote.connectionParameters.accessToken = self.accessToken
  appRemote.delegate = self
  return appRemote
}()

Configure Initial Music

iOS requires us to define a playURI (as shown in the last step) in order to play music to wake up the Spotify main application. This is an iOS-specific requirement. This can be:

An empty value: If empty, it will resume playback of user’s last track or play a random track. If offline, one of the downloaded for offline tracks will play. Example:

self.playURI = ""

A valid Spotify URI: Otherwise, provide a Spotify URI. Example:

self.playURI = "spotify:track:20I6sIOMTCkB6w7ryavxtO"

Authorizing and Connecting to Spotify

We’ll next need to initiate authorization and connect to Spotify.

func connect()) {
  self.appRemote.authorizeAndPlayURI(self.playURI)
}

This, upon a successful connection, will invoke the appRemoteDidEstablishConnection(_ appRemote: SPTAppRemote) method we defined earlier.

Subscribing to state changes

We’ll need to invoke a request to subscribe to player state updates, which we can do in the appRemoteDidEstablishConnection method:

func appRemoteDidEstablishConnection(_ appRemote: SPTAppRemote) {
  // Connection was successful, you can begin issuing commands
  self.appRemote.playerAPI?.delegate = self
  self.appRemote.playerAPI?.subscribe(toPlayerState: { (result, error) in
    if let error = error {
      debugPrint(error.localizedDescription)
    }
  })
}

And inside of the playerStateDidChange, we can begin logging the output:

func playerStateDidChange(_ playerState: SPTAppRemotePlayerState) {
  debugPrint("Track name: %@", playerState.track.name)
}

Cleaning up

When the user switches from our application, we should disconnect from App Remote. We can do this by inserting the following code into our applicationWillResignActive method:

func applicationWillResignActive(_ application: UIApplication) {
  if self.appRemote.isConnected {
    self.appRemote.disconnect()
  }
}

And similarly when a user re-opens our application, we should re-connect to App Remote. We can do by inserting the following code into our applicationDidBecomeActive method:

func applicationDidBecomeActive(_ application: UIApplication) {
  if let _ = self.appRemote.connectionParameters.accessToken {
    self.appRemote.connect()
  }
}

Or if you are using UIScene:

func sceneDidBecomeActive(_ scene: UIScene) {
  if let _ = self.appRemote.connectionParameters.accessToken {
    self.appRemote.connect()
  }
    }

func sceneWillResignActive(_ scene: UIScene) {
  if self.appRemote.isConnected {
    self.appRemote.disconnect()
  }
}

Having issues? You can take a look at a full example of AppDelegate.swift by clicking here. For a SceneDelegate example click here.

Next Steps

Congratulations! You’ve interacted with the Spotify iOS SDK for the first time. Time to celebrate, you did great! 👏

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

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