Guidelines for surfacing Categorized Content Recommendations in your mobile app.

Introduction.

The iOS and Android SDKs offer the possibility to consume categorized recommendations. These have been created to fit some specific use cases, but there are also some generic categories that have proven to be a good start for recommendations in a variety of different contexts. Recommendations and targeted content can also be requested from our web api in the form of a users top tracks, genre recommendations and recommendations based on artists and tracks. The focus of this guide, however, is the content categories available through our mobile SDKs.

Currently the available categories are Fitness, Navigation, and Sleep & Wake. On the personalized side there are Your Playlists, Your Albums, and Recently Played content that can be provided for the user through the SDKs if not specifying a particular category (default recommendations).

We are continuously working on adding new categories and update the content in the existing ones. The content in these categories will change and new categories will be added and made available for you to use.

Requirements

Recommendations can only be surfaced if the Spotify app is installed, authorized and the user is “Connected”. You need:

  • iOS and/or Android SDKs implemented
  • Spotify app installed on users phone
  • User logged in
  • User is “connected” to Spotify (has authorized your app by granting the scopes you requested)

Read more about users authorizing your app in the Authentication and Authorization part of the SDKs documentation for Android and iOS and refer to the Connection Flow Guide for suggestions on how to create a good experience.

Rendering content

When rendering the content there are a few things to keep in mind. It is important that both the content name, type and creator are visible (creator only a requirement on playlists) and we also recommend you to display the image belonging to each respective content item for a richer experience.. For the most part, recommendations are playlists, aside from the “Recently Played” category, which consists of many different content types. Please note that different types of content have different visual treatment. It is your responsibility as a developer to ensure that these are respected. This means rounded image/thumbnails for artist entities and squares for playlists, tracks, and albums.

Some of our categorized content have sub categories. These are there to divide the content into different categories within a specific context. For example, when creating something where sleep recommendations are your choice for content, we suggest that you divide the recommendations into sleep sub-categories provided by us to set better expectations for your users (i.e. nature sounds, melodic playlists, podcasts for sleep etc.)

If choosing to display multiple subcategories, we suggest displaying a few items with the option to expand the category/subcategory to reveal more. This way your users will get a better overview of the different categories available before choosing one to dive into. Example of recommendation categories

It is mandatory to implement a way to link into the context of the content in the Spotify App as stated in our T&C. This can be achieved by incorporating an overflow menu that offers a link into the content in our app. This overflow menu could also house other features like “save to your library” etc. How to implement the linking along with proper tracking is described in our content linking guide.

In all cases, whenever displaying content from Spotify in your app, it should also be clear that the content comes from Spotify. Displaying attribution in form of the Spotify logo alone or in combination with a short message stating that the content is coming from Spotify are two ways of doing this. Refer to our branding guidelines on how to display different types of assets.

What to show

In general we suggest you start with default recommendations, which contains “Recently Played” and other personalized content. It is a fast way to give your users familiar content that we already know they like. It sets your users on a quick path to get audio playing. They can then deep dive into more content by jumping over to the Spotify App.

Use the other categories if they make sense for your use case. Some of the categories have a number of Recently Played items in them so test the responses first if you are planning on using multiple categories. The content in these categories are dynamic and will change over time. Example of recommendation categories

Free and Premium Spotify users

Generally Spotify Free users are shuffle-restricted, even in the context of your app. Being shuffle-restricted means that a user cannot play on demand, but Spotify will shuffle audio for them within a set context (album, playlist etc.). When differentiating between the Spotify user types, we choose to look at capabilities. Capabilities may shift in different markets within the Free and Premium products so it is important to look at the user types as having on demand capabilities or not, first and foremost.

To find out if a user with a Spotify account can play on demand (i.e is not shuffle-restricted) use the UserAPI in the Android SDK and the SPTAppRemoteUserAPI in the iOS SDK. In this way, you can determine if the user is a has on demand capabilities or not and handle how you render and communicate with your users accordingly.

To set expectations, it is good practice to subtly remind users lacking on-demand capabilities, that their experience is shuffle restricted. This is also the place where you can inform your users how to get on-demand capabilities, by upgrading to our Premium product. You can use a predefined uri to link to the Premium value proposition page in our app:

  • spotify:upsell:premium_in_app_destination (Android)
  • spotify:internal:iap:upsell (iOS)

Note that these will only make sense if the user does not have on-demand capabilities. These URI:s can be changed in the future, so using a fallback or only linking to the Spotify web site is a preferred pattern.

https://www.spotify.com/is/premium/

Refer to our Content linking Guide when linking into Spotify, or to the web from your app.

iOS Specific

Using the content api, you can fetch content in each category sending in a string for a predefined type. As new categories are added they can be accessed by using the matching strings without needing to update the SDK. More about the API and available categories here

Currently Available Categories:

  • Root (Access to spotify home content)
  • Default (Recently Played/For you playlists)
  • Navigation (Contextualized Car and Navigation content)
  • Fitness (Contextualized Fitness content)
  • Wake (Contextualized content to wake up to and start your day)
  • Sleep (Contextualized content to relax and fall alseep to)

Android Specific

In Android you consume the recommendations using our getRecommendedContentItems To get the subcategories and drill down deeper in the content use the getChildrenOfItem method. Read more about how to consume recommendations on Android here.

Currently the following categories (types) are available for Android:

  • Default (Recently Played/For you playlists)
  • Automotive (Car specific targeted content)
  • Navigation (Contextualized Car and Navigation content)
  • Fitness (Contextualized Fitness content)
  • Wake (Contextualized content to wake up to and start your day)
  • Sleep (Contextualized content to relax and fall alseep to)