Connection Flow Guidelines to authorize your app with users’ Spotify Account.
Introduction.
In order to integrate Spotify in your mobile app you need your user to grant you permissions. This guide focuses on how to present this “auth flow” to your user on mobile and create a low friction experience, making the authorization as quick and understandable as possible. Depending on what kind of functionality you are looking to provide, there might be multiple scopes needed. For most mobile integrations, looking to remote control the Spotify app with our mobile SDKs, the app-remote control-scope is sufficient. You can read more about the technical details under our iOS SDK/Android SDK documentation and also find a list of all available scopes here.
Discoverability.
When thinking about discoverability, keep an emphasis on surfacing music at meaningful times. People are excited to introduce music into their routines so it’s important to surface the entry point, for turning on playback controls or any other Spotify powered feature you are building, within the context where the feature will be used.
Here are some examples of ways to introduce music to your experience for your users:
The “full” example above presents a landing screen for cases where users do not have the Spotify App installed, or have not authorized your app yet. This is an opportunity to describe the experience and the value of music in your app.
Announcing music in your app and checking availability.
In most of our guides we talk a lot about discovery and how to promote music in your context. This is because it is important to instantly convey the message of why music will contribute to a better experience, adding another layer in your app. When announcing to your users that Spotify is available as a provider of music in your context, it is therefore important to display an educational message describing how and why music fits with what your app is doing.
Connecting via Interstitial.
Below is a suggestion for calling out that your users need to connect to Spotify before they can start enjoying music in the context of your app:
Connect via dedicated screen.
If you want to offer more granular feedback to eliminate surprises for your user and clearly state what actions need to be taken to connect to Spotify you can render a call to action with either of the following 3 states:
- Need to install
- Need to connect (also shown when the user has logged out of the Spotify App).
- Need to update (can be shown if a certain version of Spotify is needed to enjoy the integration and work with your version of the SpotifySDK)
A fourth state exists when the integration itself is shown (everything is good to go all steps has been taken by the user to enjoy the integration).
Making sure Spotify is installed.
When integrating with the Spotify SDK, your users need to have the Spotify App installed in order for your app to remote control the Spotify client. This calls for checking if the Spotify App is installed before launching the connect flow (also referred to as the Auth flow). How to check if Spotify is installed is described in our Content Linking Guide here .
Before determining if Spotify is installed it is important to check if Spotify is available in the current market your user is in. On Android that is done by querying if the Spotify App is available in the Play Store in users current market, while on iOS it is not as simple. For iOS you need to keep a record of which markets we operate in. Updated information on what markets Spotify is available in is posted continuously here. If the Spotify App is not installed, but available in the current users market you should send them to the Play Store_App Store for download. It is important for Spotify to track the events of sending a user to download our client. It is therefore a requirement to send a request to our tracking endpoint before dropping your user off in the Play Store_App Store. Read how to properly implement that call in our content linking guide. Note that after download (and signup if not already a Spotify user) is completed the users have to manually open up your app again to start the connection flow. Due to being dependent on the Spotify App, it is important that these checks are performed every time the user is about to use your Spotify integration, to cover the edge case of your user having deleted the Spotify App since their last session.
When Spotify is installed: “Connecting” and granting your app the requested scopes.
Granting permissions is handled by the Spotify SDK Auth. Read more about Android Auth lib here and iOS Auth here (if only needing the scope for remote controlling Spotify there is a simpler way to authorize your app built in). The dialogue where the user grants you permissions is only shown for new users or if a user has revoked your permissions. If the user is logged out of the Spotify App at the moment of Authorization they will be asked to log in/signup first before the Auth screen is presented. After login and/or auth the user should be taken back to your app. Spotify will link back to the redirect URI provided in your app settings.
Error connecting
If for some reason there is a problem connecting to Spotify that should be displayed to the user in an error message.