Getting started with Android SDK
Beta

Introduction

This tutorial leads you step-by-step through the creation of a simple app that uses the Spotify App Remote SDK to play a playlist. We show you how to:

Play a playlist from a URI
Subscribe to PlayerState of the Spotify app and read its data

If you are new to developing Android apps, we recommend reading the tutorials on Google's Android developer portal.

Important policy notes

Prepare Your Environment

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 whitelist a redirect URI that the Spotify Accounts Service will use to callback to your app after authorization.

You also should add your package name and app fingerprint as they're used to verify the identity of your application.

Select "Android" for the question asking which APIs are you planning to use.

Install Spotify App

App Remote SDK requires the Spotify app to be installed on the device. Install the latest version of Spotify from Google Play on the device you want to use for development. Run the Spotify app and login or sign up.

Download the SDK

Download the Spotify Android SDK from our GitHub.

Create Your App

Create or make sure you have an Android app with at least one Activity or Service in which you can put your code to connect to Spotify.

Edit your MainActivity to look like this:

Kotlin

Java


_21class MainActivity : AppCompatActivity() {
_21
_21    override fun onCreate(savedInstanceState: Bundle?) {
_21        super.onCreate(savedInstanceState)
_21        setContentView(R.layout.activity_main)
_21    }
_21
_21    override fun onStart() {
_21        super.onStart()
_21         // We will start writing our code here.
_21    }
_21
_21    private fun connected() {
_21        // Then we will write some more code here.
_21    }
_21
_21    override fun onStop() {
_21        super.onStop()
_21        // Aaand we will finish off here.
_21    }
_21}

Add the App Remote SDK

Unzip the App Remote SDK zip file that you downloaded. Add the library to your project by importing it as a module. In the Project side bar in Android Studio (View > Tool Windows > Project), right click your project's root folder and navigate to New > Module.

New module GUI

In the New Module window, choose the option Import .JAR/AAR Package. Click Next.

Import Jar GUI

Press the "..." button and locate the spotify-app-remote-release-version.aar under the app-remote-lib folder in the unzipped bundle. Click Open and choose a suitable subproject name. We're using spotify-app-remote in this example. Click Finish to import the .aar into your project.

Create new module GUI

When updating the App Remote SDK with future updates of the SDK, simply replace the .aar file in your project's directory.

Add a dependency on the spotify-app-remote module to your app by adding the imported subproject and Gson to your app's build.gradle file. It is important that the name that you specify in the build.gradle file is the same as the subproject name you decided on.


_10dependencies {
_10    // your app dependencies
_10    implementation project(':spotify-app-remote')
_10    implementation "com.google.code.gson:gson:2.6.1"
_10}

Since version 0.2.0 of the App Remote SDK, Gson is used by default for serializing and deserializing the request. Jackson is also supported. If you would like to use Jackson instead please see the FAQ here.

Import Dependencies


_10import com.spotify.android.appremote.api.ConnectionParams;
_10import com.spotify.android.appremote.api.Connector;
_10import com.spotify.android.appremote.api.SpotifyAppRemote;
_10
_10import com.spotify.protocol.client.Subscription;
_10import com.spotify.protocol.types.PlayerState;
_10import com.spotify.protocol.types.Track;

Set up your Spotify credentials

Kotlin

Java


_10private val clientId = "your_client_id"
_10private val redirectUri = "http://com.yourdomain.yourapp/callback"
_10private var spotifyAppRemote: SpotifyAppRemote? = null

Authorize Your Application

To be able to use the App Remote SDK the user needs to authorize your application. If they haven't, the connection will fail with UserNotAuthorizedException. To allow the user to authorize your app, you will use the built-in authorization described below.

Authorizing the user using the built-in auth flow

For this use-case, you don't have to add the Authorization Library to your application. You can request that the authorization view is shown to users who have not approved the app-remote-control scope by passing the flag showAuthView in the ConnectionParams. The scope is automatically requested for you by the library.

Add the following to your onStart method:

Kotlin

Java


_10// Set the connection parameters
_10val connectionParams = ConnectionParams.Builder(clientId)
_10    .setRedirectUri(redirectUri)
_10    .showAuthView(true)
_10    .build()

Built-in auth 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

Authorizing user with Single Sign-On library

Download and add Authorization Library to your project as described in this guide.

Create and send the authorization request as described in the Android SDK Authorization Guide. You need the app-remote-control scope to use the Spotify App Remote SDK.

Connect to App Remote

The first thing we need to do is to use the SpotifyAppRemote.Connector to connect to Spotify and get an instance of SpotifyAppRemote. To do this, we call the connect method using the connectionParams we defined above. Add the following to your onStart method.

Kotlin

Java


_13SpotifyAppRemote.connect(this, connectionParams, object : Connector.ConnectionListener {
_13    override fun onConnected(appRemote: SpotifyAppRemote) {
_13        spotifyAppRemote = appRemote
_13        Log.d("MainActivity", "Connected! Yay!")
_13        // Now you can start interacting with App Remote
_13        connected()
_13    }
_13
_13    override fun onFailure(throwable: Throwable) {
_13        Log.e("MainActivity", throwable.message, throwable)
_13        // Something went wrong when attempting to connect! Handle errors here
_13    }
_13})

Play a Playlist

To play a playlist given a Spotify playlist URI, we are going to connect to the Spotify app and use the PlayerApi command. From there we can get the PlayerApi directly and call play. Add the following to your private connected method:

Kotlin

Java


_10// Play a playlist
_10spotifyAppRemote.playerApi.play("spotify:playlist:37i9dQZF1DX2sUQwD7tbmL")

Run the application and you should hear some feel-good indie tunes playing on your phone. If you prefer something more relaxing, why not try some sweet piano music spotify:playlist:37i9dQZF1DX7K31D69s4M1. If you don't hear music playing and end up in the onFailure callback above, please read up on connection errors and try again.

The PlayerApi offers, in addition to the play(uri) method we use above, the ability to subscribe to and poll for the state of the Spotify player. Add the following to your code to subscribe to PlayerState and log the track title and artist of the song that will be playing:

Kotlin

Java


_10// Subscribe to PlayerState
_10 spotifyAppRemote.playerApi.subscribeToPlayerState().setEventCallback {
_10    val track: Track = it.track
_10    Log.d("MainActivity", track.name + " by " + track.artist.name)
_10}

Run the app again. You should now see a log with the track name and artist of the currently playing track.

Disconnecting from App Remote

Don't forget to disconnect from App Remote when you no longer need it. Add the following to your onStop method.

Kotlin

Java


_10override fun onStop() {
_10    super.onStop()
_10    spotifyAppRemote?.let {
_10        SpotifyAppRemote.disconnect(it)
_10    }
_10
_10}

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 best practices for handling App Remote SDK interactions and connections in your Android application.
Dive into other things you can do with the SDK in the App Remote SDK Reference.

Source Code

The Quick Start source code is below. Copy into your Main Activity.

Kotlin

Java


_70package com.yourdomain.yourapp;
_70
_70import android.os.Bundle;
_70import android.support.v7.app.AppCompatActivity;
_70
_70import android.util.Log;
_70
_70import com.spotify.android.appremote.api.ConnectionParams;
_70import com.spotify.android.appremote.api.Connector;
_70import com.spotify.android.appremote.api.SpotifyAppRemote;
_70
_70import com.spotify.protocol.client.Subscription;
_70import com.spotify.protocol.types.PlayerState;
_70import com.spotify.protocol.types.Track;
_70
_70class MainActivity : AppCompatActivity() {
_70
_70    private val clientId = "ad0911afa57949bba362003f601876b2"
_70    private val redirectUri = "https://com.spotify.android.spotifysdkkotlindemo/callback"
_70    private var spotifyAppRemote: SpotifyAppRemote? = null
_70
_70    override fun onCreate(savedInstanceState: Bundle?) {
_70        super.onCreate(savedInstanceState)
_70        setContentView(R.layout.activity_main)
_70    }
_70
_70    override fun onStart() {
_70        super.onStart()
_70        val connectionParams = ConnectionParams.Builder(clientId)
_70            .setRedirectUri(redirectUri)
_70            .showAuthView(true)
_70            .build()
_70
_70        SpotifyAppRemote.connect(this, connectionParams, object : Connector.ConnectionListener {
_70            override fun onConnected(appRemote: SpotifyAppRemote) {
_70                spotifyAppRemote = appRemote
_70                Log.d("MainActivity", "Connected! Yay!")
_70                // Now you can start interacting with App Remote
_70                connected()
_70            }
_70
_70            override fun onFailure(throwable: Throwable) {
_70                Log.e("MainActivity", throwable.message, throwable)
_70                // Something went wrong when attempting to connect! Handle errors here
_70            }
_70        })
_70    }
_70
_70    private fun connected() {
_70        spotifyAppRemote?.let {
_70            // Play a playlist
_70            val playlistURI = "spotify:playlist:37i9dQZF1DX2sUQwD7tbmL"
_70            it.playerApi.play(playlistURI)
_70            // Subscribe to PlayerState
_70            it.playerApi.subscribeToPlayerState().setEventCallback {
_70                val track: Track = it.track
_70                Log.d("MainActivity", track.name + " by " + track.artist.name)
_70            }
_70        }
_70
_70    }
_70
_70    override fun onStop() {
_70        super.onStop()
_70        spotifyAppRemote?.let {
_70            SpotifyAppRemote.disconnect(it)
_70        }
_70
_70    }
_70}

Getting started with Android SDK Beta

Introduction

Prepare Your Environment

Register Your App

Install Spotify App

Download the SDK

Create Your App

Add the App Remote SDK

Import Dependencies

Set up your Spotify credentials

Authorize Your Application

Authorizing the user using the built-in auth flow

Authorizing user with Single Sign-On library

Connect to App Remote

Play a Playlist

Subscribe to PlayerState

Disconnecting from App Remote

Next Steps

Source Code

Getting started with Android SDK
Beta