DOCSEARCHbyAlgolia
Submit Docs

Spotify Android SDK

repository·master·Indexed 19 days ago

https://github.com/spotify/android-sdk

A set of tools for Android developers to interact with the Spotify service. It consists of two main components: the Spotify App Remote SDK for controlling playback and accessing metadata via the Spotify app, and the Spotify Authentication Library for handling OAuth flows to obtain access tokens for the Spotify Web API.

Tokens
2.9K
Snippets
3
Records
14
Agent score
68%

What's inside spotify-android-sdk

  1. Overview of Spotify App Remote SDK components

    master

    The SDK is structured around several key interfaces and models that act as an entry point to the Spotify app:

    Core Interfaces

    • SpotifyAppRemote: The primary entry point for all interactions. It provides access to specialized APIs like PlayerApi and ImagesApi.
    • Connector: A component used to receive an instance of SpotifyAppRemote.

    Specialized APIs

    • PlayerApi: Used for playback commands (play by URI, resume/pause, shuffle) and subscribing to PlayerState and PlayerContext updates.
    • UserApi: Used to check user capabilities (e.g., if they can play on-demand) and manage content in the user's library.
    • ImagesApi: Used to download cover art via URI.
    • ContentApi: Used to retrieve lists of content.
    • ConnectApi: Used to control which device the Spotify app should play music on.

    Data Models

    • PlayerState: Provides information on the current track, playback status (playing/paused), current position, and if the track is in the user's library.
    • PlayerContext: Provides metadata about the current context, such as the title of the playing album or playlist.
    • Album, Artist, Track: Standard metadata models.

  2. Choose between auth and store library flavors

    master

    Since version 2.1.0, the library provides two flavors that change the behavior when the Spotify application is not installed on the device:

    • auth: Opens the web browser to perform the Spotify login.
    • store: Redirects the user to the Android Play Store to download the Spotify application.

  4. Understand the Spotify Android SDK components

    master

    The Spotify Android SDK is composed of two distinct libraries that can be used together or independently depending on your application's requirements:

    1. Spotify App Remote: Used for managing audio playback via the Spotify Music app. It provides classes for music playback control and accessing metadata. It uses the app-control-scope for built-in authentication and does not require token exchange.
    2. Spotify Authentication Library: Used for handling the OAuth authentication flow to obtain access tokens. These tokens can be used for playback or to make calls to the Spotify Web API. This library is an open-source project.

    Use the App Remote if you only need to control playback. Use the Authentication Library if you need user login, Web API capabilities, or additional scopes.

  5. How the Spotify App Remote SDK works

    master

    The Spotify App Remote SDK is a lightweight library (< 300k) that allows your application to interact with the Spotify app running in the background as a service.

    Key Concepts:

    • Offloaded Processing: The Spotify app handles the heavy lifting, including playback, networking, offline caching, and OS music integration (audio focus, lockscreen controls, etc.).
    • Synchronization: Playback and metadata stay in sync between your app and the Spotify app.
    • Connectivity: While playback can occur offline for cached content, your app cannot connect and start communicating with the Spotify app unless there is an active internet connection.
    • Metadata: You can retrieve metadata for the currently playing track and context without needing separate Web API calls.

  6. Get started with the Spotify Android SDK

    master

    To begin using the SDK, follow these steps:

    1. Follow the official quick start documentation at Spotify for Developers.
    2. Add the libraries as module dependencies to your Android project.
    3. Review the sample implementations provided in the repository:
      • app-remote-sample for App Remote usage.
      • auth-sample for Authentication Library usage.

  8. Authenticate and authorize the Spotify App Remote SDK

    master

    To control playback remotely, your application must obtain user permission. There are two primary methods:

    Method 1: Using the Android Authentication Library (Recommended for complex needs)

    Include the Android Authentication Library in your project and request the app-remote-control scope.

    • Use case: Use this if you need to request additional scopes or need an access token to communicate with the Spotify Web API.

    Method 2: Built-in Authorization Mechanism

    Request to show the authorization view when connecting to Spotify. The library will automatically request the app-remote-control scope and display the auth view if the user hasn't agreed yet.

    • Limitations: You cannot retrieve the token from the Remote SDK using this method, and you cannot request additional scopes.
    • Use case: Best for simple playback control implementations.

  9. Get started with the Spotify App Remote SDK

    master

    To begin using the Spotify App Remote SDK (Android), follow these steps:

    1. Download the library: Obtain the library files from the app-remote-lib directory of the repository.
    2. Follow the Beginner's Tutorial: Refer to the official Beginner's Tutorial to set up your build environment and create a simple app that connects to Spotify, plays a playlist, and subscribes to PlayerState.
    3. Explore the Demo App: Review the source code in the demo directory for full examples of how to use the available APIs.

    Requirement: The Spotify Android app must be installed on the user's device for the SDK to function.

  10. Integrate the Spotify Auth Library

    master

    To use the Spotify Auth Library for authenticating users and fetching authorization codes or access tokens, follow these steps:

    1. Add MavenCentral to your repositories: Ensure mavenCentral() is included in your repositories block in build.gradle.
    2. Add the dependency: Add the following line to your app's build.gradle file: implementation "com.spotify.android:auth:<version>"
    3. Configure Manifest Placeholders: For version 2.0.0 and above, you must provide the scheme and host of your redirect URI in your defaultConfig block using manifestPlaceholders.
    4. Permissions and Activities: The library automatically merges the INTERNET permission and the com.spotify.sdk.android.auth.LoginActivity into your manifest.
    // 1. Repositories block
repositories {
    mavenCentral()
    ... 
}

// 2. Dependencies block
dependencies {
    implementation "com.spotify.android:auth:<version>"
}

// 3. DefaultConfig block (Example for redirect URI 'spotify-sdk://auth')
defaultConfig {
    manifestPlaceholders = [redirectSchemeName: "spotify-sdk", redirectHostName: "auth"]
    ... 
}

  11. Handle Connection errors in ConnectionListener.onFailure()

    master

    Connection errors are delivered via the onFailure method of the ConnectionListener interface. These errors can occur at any point from the initial connect call until the client disconnects. You should implement logic within onFailure to inspect the exception type and guide the user or application state accordingly.

    // Example pattern for handling connection failures
connectionListener = new ConnectionListener() {
    @Override
    public void onFailure(ConnectionError error) {
        // Handle specific error types here
    }

    @Override
    public void onConnected() {
        // Handle successful connection
    }
};