cordova-spotify-oauth

Cordova Spotify OAuth Plugin

Easy Spotify authentication for Apache Cordova / PhoneGap apps

API Documentation

Features

This plugin provides a simple way of authenticating a user with the Spotify API using the authorization code flow.

The plugin uses SFSafariViewController and Chrome Custom Tabs, if available. This also means it will only work on iOS 9 and above (but this shouldn't be a problem anymore).

Examples

The plugin consists of two functions clobbered onto cordova.plugins.spotifyAuth.

Log in

const config = {
  clientId: "<SPOTIFY CLIENT ID>",
  redirectUrl: "<REDIRECT URL, MUST MATCH WITH AUTH ENDPOINT AND SPOTIFY DEV CONSOLE>",
  scopes: ["streaming"], // see Spotify Dev console for all scopes
  tokenExchangeUrl: "<URL OF TOKEN EXCHANGE HTTP ENDPOINT>",
  tokenRefreshUrl: "<URL OF TOKEN REFRESH HTTP ENDPOINT>",
};

cordova.plugins.spotifyAuth.authorize(config)
  .then(({ accessToken, expiresAt }) => {
    console.log(`Got an access token, its ${accessToken}!`);
    console.log(`Its going to expire in ${expiresAt - Date.now()}ms.`);
  });

Log out

cordova.plugins.spotifyAuth.forget();

Installation

cordova plugin add cordova-spotify-oauth

Usage

The plugin implements the OAuth Authorization Code flow for the Spotify API. This allows you to obtain access and refresh tokens for user related-actions (such as viewing and modifying their library, streaming tracks via the SDKs, etc.). Therefore, additional preparation in addition to installing the plugin is required.

Protocol registration

The plugin uses custom URL schemes (universal links support will follow) to redirect back from the browser into the app.

You need to register the callback protocol inside the App Info.plist so that iOS knows which app to start when it is redirected when the authentication is done. If you want to use Chrome Custom Tabs (optional, but 110% nice), you must also register the URL scheme and path you will be redirected to within the AndroidManifest.xml file.

Take a look at this repository to see how it's done for both cases.

Spotify Developer Registration

You need to register your custom redirect URL within the Spotify Developer console. Make sure you register the exact value you use within your code (including trailing slashes, etc.).

Token Exchange Service

The authorization code flow requires server code for security. These come in the form of two HTTP endpoints, one for the auth code exchange, and the other one for access token refresh. The SDK will POST application/x-www-form-urlencoded data and expects JSON back. Ensure you have proper CORS config set up.

To easily implement them, we built a Serverless service for AWS Lambda over in the oauth-token-api folder. Make sure you install the Serverless Framework properly! To resolve the project dependencies, please use yarn as shown below before deploying the service.

For the execution of the functions to work you need to set some environmental configuration in the file oauth-token-api/.env

CLIENT_ID="<Your Spotify Client ID>"
CLIENT_SECRET="<Your Spotify Client Secret>"
CLIENT_CALLBACK_URL="<The callback url of your app>" # e.g. "festify-spotify://callback"
ENCRYPTION_SECRET="<Secret used to encrypt the refresh token - please generate>"

You can then deploy the functions like this:

cd oauth-token-api
yarn install
serverless deploy

The serverless CLI will then print the URL where the functions can be reached. These are the values needed for tokenExchangeUrl and tokenRefreshUrl.

JavaScript usage

Head over to the API Documentation.

Contributing

Pull requests are very welcome! Please use the gitmoji style for commit messages.