This tutorial leads you step-by-step through the creation of a simple app that uses the Spotify Android SDK to play an audio track.

Please note: the Android SDK 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.

About This Tutorial

This tutorial leads you step-by-step through the creation of a simple app that uses the Spotify Android SDK to play an audio track. We show you how to:

  • Set up an Android Studio project for your app,
  • Authenticate a user,
  • Play an audio stream from Spotify. (Premium accounts only)

The app we will create is very simple. It has just a single Activity created by Android Studio. When the app starts it authenticates the user, gets the user’s authorization to stream a track, and starts playing that track. The complexities of Android app development are beyond the scope of this tutorial; our aim is simply to help you set up your environment and project correctly and to make sure you can connect to the Spotify service. If you are new to developing Android apps, we recommend reading the tutorials on Google’s Android developer portal.

We will be calling several of the Spotify Android SDK functions in our code. Full documentation for these functions is available within the Android SDK’s download package on GitHub or online. The package also contains a README that contains important information about the SDK, including set-up information.

Preparing Your Environment

To use the Spotify Android SDK, the first thing you will need is a Spotify user account (Premium or Free). To get one, simply sign up at www.spotify.com.

Note: this tutorial makes use of the streamingscope, therefore the user who logs in must have a Spotify Premium account.

Next, download the Android Studio for your platform and install it using the default settings. You may also need to download and install a compatible Java SE Development Kit if you do not already have one installed on your system. Note that the Java Development Kit you install must match your operating system type, for example, 64-bit Windows user should download the 64-bit Java SE package.

This tutorial is based on Android Studio 1.5.1. If you are using a different version of Android Studio, please make sure your Gradle files are compatible with the version that you have installed.

Creating a New Project

Open Android Studio and create a New Project.

In this tutorial, the values that you enter here will be substituted in code examples with the values applicationname and companydomain.

Set the Minimum SDK version to “API level 15: Android 4.0.3 (Ice Cream Sandwich)”.

When you are asked to “Add an activity to Mobile”, select Blank Activity.

Give the activity the name MainActivity, the layout the name activity_main, and the title MainActivity.

These values will be used later in the code examples. If you chose different values you will need to modify the subsequent code accordingly.

Click Finish. (If you get a Windows security alert, click Allow Access.) Android Studio will now create your project.

If Android Studio fails to create the project, look in the “Messages” tab at the bottom of the screen. It is likely that you need to update or install extra SDK dependencies, such as the Android SDK Build-tools. Open the Android SDK Manager from Android Studio’s Tools > Android > SDK Manager menu option and check for and install any updates or dependencies.

Note: you may still have an error importing from Gradle; ignore this error for the moment.

Installing the Android SDK

Download the Spotify Android SDK framework zip file from GitHub and unzip it.

In a file explorer (not Android Studio), drag the unzipped spotify-auth-version.aar and spotify-player-version.aar files into the /app/libs directory in your project’s root directory.

In Android Studio, open the app directory (which can also be labelledModule: app) and then open thebuild.gradle file. Double check to make sure that you edit the gradle file that is located in the app directory. Change the contents of the file to the following:

apply plugin: 'com.android.application'

android {
    compileSdkVersion 23
    buildToolsVersion "23.0.1" // Note: this version should match the latest build-tools version
                               // that you installed in the SDK manager

    defaultConfig {
        applicationId "companydomain.applicationname"
        minSdkVersion 15
        targetSdkVersion 23
        versionCode 1
        versionName "1.0"
    }
    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

repositories {
    mavenCentral()
    flatDir {
        dirs 'libs'
    }
}

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    
    // This library handles authentication and authorization
    compile 'com.spotify.sdk:spotify-auth:1.0.0-beta12@aar'
    
    // This library handles music playback
    compile 'com.spotify.sdk:spotify-player:1.0.0-beta12@aar'
    
    // All other dependencies for your app should also be here:
    compile 'com.android.support:appcompat-v7:23.1.1'
}

The values you provide in the code above (buildToolsVersion, applicationId, and the aar file version) must match the particulars of your installations. Don’t forget to add the flatDir entry to the repositories section. Otherwise Gradle will not be able to locate the aar.

Note that, as shown in the second “compile” line in the code above, the Gradle file dependency is identified by using a colon in place of the first dash of the aar file name. The colon is actually a separator between the parts of the dependency. You can find more about Gradle dependency syntax here: http://www.gradle.org/docs/current/userguide/dependency_management.html

After doing this, in Android Studio, select Tools > Android > Sync Project with Gradle Files. You should now have no error messages in the messages pane. If you still have error messages, troubleshoot the problem before continuing.

Registering Your Application

The Android SDK uses the OAuth endpoints provided by the Spotify Accounts Service to authenticate the application user and to authorize your application to access the Spotify service. You will need to register your application at My Applications and obtain a client ID.

When you register your app you will also need to white list a redirect URI that the Spotify Accounts Service will use to callback to your app after authorization:

setting-your-callback

The redirect URI should have the general form:

yourcustomprotocol://callback

Do not use https or http or other common protocols as a prefix, otherwise you will find that the callback opens your client’s web browser or other program — make the protocol prefix unique so that your app has a chance to listen for it.

Later, you will need to enter this redirect URI (and, separately, the protocol and callback address) in your application code.

Registering Application Fingerprints

To communicate with Spotify you need to register one or more fingerprints in My Applications page in the Developer Portal. This value is used to authenticate your application against Spotify client.