This document is intended for anyone who plans to make apps for Spotify. It outlines basic requirements, the app approval process, as well as some general resources and recommended practices.
Developers should read both the developer guidelines and the design guidelines. The developer guidelines also contains a boilerplate app to help you get started quickly, as well as other relevant information for developers.
Spotify provides frameworks to help partners fulfill the app requirements, including:
- Creating UI elements (such as album covers, playlists, buttons etc.)
- Playing, creating and manipulating playlists
- Searching for content
- Sharing content
Read more about these frameworks in the developer guidelines.
For interacting with the outside world, your application will be given a Spotify URI similar to that of other Spotify entities. This URI is constructed in the following manner:
For example, spotify:app:mycoolapp
The URI can have additional arguments appended to it. To learn more about the application URI and how to use it, read our Spotify Apps Developer Guidelines.
If your app is set to support multiple languages you need to make sure you have translations for each language. We provide support for internationalization in our frameworks to make it easier to support several languages. See the Spotify Apps Developer Guidelines for more information.
You are expected to design your application so that it behaves like an integral part of Spotify. This means that you should avoid full page reloads – request new elements/resources in the background and then manipulate the current page’s DOM upon arrival of new data.
In addition, make use of local storage where possible to reduce the latency of requesting resources from a remote location.
Static vs. Local Content
When designing your application, make sure to keep in mind that once submitted, the contents of your application are served by the Spotify backend and immutable until another submission is made and approved.
You need to design your application to handle the occasional loss of internet connection. Also, even though your application might be able to access your backend service, the Spotify application itself may occasionally have issues communicating with our internal services. Please respect and treat error codes and callbacks carefully, or your application will behave badly during such conditions.
You should design your application so that it behaves well even when users are limited to slower internet connections. Streaming a track inside Spotify requires a moderate 2.75G (EDGE) connection, so you will want to simulate a similar connection speed while testing to make sure that you’ve designed it correctly (i.e. load critical data first, and then not-so-critical data later).
Xcode (for Mac OS X) provides a useful connection simulator called Network Link Conditioner that will help test these conditions. For more information please visit Network Link Conditioner.
It is important that when a user returns to an app it remains in the same state in which they left it.
Since your application may be loaded and unloaded multiple times, it is recommended that you use local storage to persist UI state such as scroll position, current content, etc.
To keep a coherent look and feel in the Spotify experience you must adhere to our App Design Guidelines. Our frameworks contain several commonly used UI elements that have the correct look & feel to help you develop apps faster.
When images can’t be loaded (for example, when third party services are temporarily unavailable), a fallback solution should be used, so that a suitable locally-bundled alternative or placeholder is loaded instead.
Users on the free tier of Spotify subscriptions may have a limit on the amount of playback they have – both in terms of total playback time and the number of times an individual track can be played.
It is important that you handle this correctly: do not needlessly waste the user’s playback time, and properly handle error callbacks when a track can’t be played due to playback limits or other errors.
Currently Unavailable Content
Use of local tracks should be done sparingly. If you’ve got content that you would like to include or link to that is currently not available on Spotify, you can still generate “local tracks” that the Spotify application can interact with. Such tracks will be playable if:
- The user happens to have local copies of the tracks in question (as MP3s, or any other format that the Spotify application accepts) that Spotify knows about (i.e. they’re listed in the “local files” view in Spotify).
- Spotify acquires the rights at a future time.
The Spotify application will always try to resolve an alternate version for local tracks, so it’s better to incorporate them than to skip them just because they’re not available in Spotify’s catalogue at the moment. However, make sure that the local track will be skipped, if the user doesn’t have it in their catalogue.
The format of our local tracks looks like this:
spotify:local:An+artist+name:An+album+name:A+track+name:duration (where duration is in seconds).
A real-world example:
URIs constructed in the manner can be used as ordinary tracks in the JS API.
It’s important to bear in mind that users on the free tier of Spotify will have adverts inserted into their playback. Your application must react to the the appropriate callbacks when the current track changes and update your UI accordingly. In addition, when an advert is playing, skipping and seeking tracks is disabled.
Non-Spotify Audio Content
You are not allowed to playback non-Spotify audio content.
Video content is not supported.
Flash is not supported.
Modifying User Content
Your application must not modify user content such as playlists, even if you have the application permissions to do so, unless you explicitly ask the user for permission to do so first. This must be an opt-in feature of your application, not opt-out.
User Tracking & Analytics
When tracking users, you must not upload any user-identifiable data or data that could be used to identify the user by cross-referencing it with your own data from the Spotify API to your service, unless the user has explicitly logged in to your service within your application and accepted the license agreement. Additionally, any tracking/analytics tools you use must not negatively affect the performance or memory usage of your application, or the Spotify application itself.
Apps that create playlist URI:s
A recommendation for when you want your app to generate playlists is as follows:
If you want to generate and save the user’s personal playlists in the app, you should not keep playlist information only saved within the app. Playlist information should instead be handled by utilizing user playlists, so that the user can access playlists as usual. They shouldn’t have to go to the app to access a certain playlist that they have created.
Currently, it is possible for an app to save a playlist, but it is not possible to edit the playlist, unless the app knows the playlist URI. The playlist URI is not given to the app when the app creates the playlist. To learn the playlist URI, the app needs to ask the user to give it to the app. This can be done by dragging and dropping the playlist from the playlist view on clients that support drag and drop. In this case, the app should state clearly to the user that the app is intending to edit and manage the playlist.
Also, make sure to use correct naming of playlists, as described in the App Design Guidelines.
The app must be able to handle large amounts of data. For example, it should be able to handle large playlists of 1000+ tracks and large Facebook accounts with 3000+ friends.
External Resources and APIs
Your application can make requests to external resources and APIs if needed.
This does not mean that you’re allowed to serve your app remotely – you must make sure to bundle all logic, layouts, graphics, etc., within your app bundle, so that it cannot be replaced during runtime (such changes would need a new submission of your application).
Only request dynamic data from your own backend, and include other data and resources within the app bundle itself. If your app relies on data from an API (such as fetching articles about a band etc), you need to make sure it can scale properly if your app gets large amounts of traffic.
Your server needs to properly handle CORS headers in server communication from apps using the Spotify Apps API 1.0. This means that your servers needs to respond with proper “Access-Control-Allow-Origin” headers. We also require apps to list all external serves and their protocols in the RequiredPermissions in the manifest. For security reasons, we also require that communication with servers should use HTTPS rather than HTTP as the protocol.
You should use the local storage HTML5 API if the platform supports it. It provides a limited amount of space to your application where you can store data that is cache-able. Please be aware that any state you save here will be local, and hence you won’t be able to restore from it if the user logs into Spotify from another computer and browses to your application.
To restore state regardless of which computer a user is currently using, please use your own backend.
User-Generated Content (UGC) is not allowed
No app that contains User-generated content (UGC) will be approved for development or distribution on the Spotify Apps platform.
Some examples including, but not limited to, what we would define as UGC are:
User uploaded audio, video, photos, lyric submissions, text including naming and commenting, chat room forums, user reviews, Wikipedia extraction, and includes where such content is pulled from Twitter- and Facebook feeds and blogs.
App Approval Process
A more detailed guide to our app approval process can be found here.
There are two processes that your app needs to be approved in before it can be released; the Concept approval and the QA approval. When the concept has been approved, the app needs to go through our QA process before release. Both the Concept and QA processes are usually done in several iterations, until we feel that the app meets an acceptable level of quality in both user interface and functionality, at which point it will be approved for release.
After a review, please ensure that at least 80% of the outstanding issues have been fixed before sending another review build to Spotify. This helps to keep down the number of iterations, which in turn will help to reach a release date much more quickly.
After an app has been approved by QA, Release Management handles the release planning and partner communications. After QA approval, a release date that suits the partner and Spotify is established. We want to choose a date that is at least a week ahead. Preferably, this is set to a Wednesday at 10:00 AM CET, though our upload window stretches from Monday to Thursday 10:00 AM to 5:00 PM CET. After a release date has been set, the partner is introduced to our PR department for sign off on any release related press material. On the release day, the partner will be contacted as soon as the app is available in the Spotify client.
Minimum requirements checklist
Before you submit your first app iteration to us, it is important to run the app towards a manual checklist. This is the same checklist that we will use to test your app. If the app passes this list of tests, it will cut down on the total time your app has to remain in the Spotify QA process. The checklist can be found here.