Client ID Swapping

Android

The Feed.fm SDK generates and stores a single random token (called the 'client ID') on the local device that is used to track a user's playback history and enforce playback restrictions. This works well when a single user plays music on a single device, but has some drawbacks when multiple users use the same device. The latest iteration of the Feed.fm Android SDK has new methods to support multiple users on the same device. These new methods also support transferring a client ID between devices so a user's playback history and feedback can follow them wherever they log in.

The Client ID

The Feed.fm client ID is a simple ASCII string up to 32 characters long that is provided to an application the first time it contacts the Feed.fm servers via the Feed.fm SDK, and looks like this:

   fmcidv1:jmgmpzwr:1z6:i5o8vn8pvj

The value is stored in SharedPreferences on Android devices and in a UserDefaults iOS devices.

The current client ID may be be retrieved on Android devices via FeedAudioPlayer.clientId. Note that this value will be null until the first time the player successfully contacts the Feed.fm servers and transitions out of the UNINITIALIZED state..

Creating and Switching Between IDs

If your application can switch between users, then it should request a new client ID for each user beyond the first, it should persist those client IDs, and it should tell the Feed.fm SDK when to switch to a different client ID. There are multiple ways to create new client id's and to switch between them, depending on whether you use a singleton FeedAudioPlayer that is shared between all users or whether you create a new FeedAudioPlayer when changing users.

Switching Client IDs with Existing FeedAudioPlayer

If your application is creating and using a singleton FeedAudioPlayer (whether via the FeedPlayerService or not), then the way to generate new client IDs and switch between them are to use the FeedAudioPlayer.clientId, FeedAudioPlayer.setClientId() and FeedAudioPlayer.createNewClientId() methods.

FeedAudioPlayer.clientId returns the player's current ID, suitable for persisting. This value is guaranteed to not be null once the player has left the UNINITIALIZED state. This value can be persisted or transferred to another device.

FeedAudioPlayer.setClientId() stores a previously retrieved client ID (from FeedAudioPlayer.clientId) on the device as the current and default client ID. This call stops any music playback and flushes all playback buffers. This call should be made when switching between users, after the player has transitioned out of the UNINITIALIZED state. Playback via the new client ID

FeedAudioPlayer.createNewClientId() asks the Feed.fm servers for a new client ID, then stores that on the device as the current client ID by calling FeedAudioPLayer.setClientId(), then returns the value to the caller via the provided listener. This method should be called when the application is switching to a new user that doesn't have a client ID associated with their account already. The client ID returned to the listener should be persisted with the new user.

Switching Client IDs with New FeedAudioPlayer

If your application creates a new FeedAudioPlayer when starting a music session and then destroys it when ending a sesssion, you can use the FeedAudioPlayer.Builder.setCreateNewClientId() and FeedAudioPlayer.Builder.setClientId() methods when creating a new FeedAudioPlayer to support multiple client ids.

If you are creating a new player for a user that doesn't have a persisted client ID yet, then call the FeedAudioPlayer.Builder.setCreateNewClientId() method while constructing your FeedAudioPlayer with a Builder, like so:

  FeedAudioPlayer player = new FeedAudioPlayer.Builder()
                                  .setToken("demo")
                                  .setSecret("demo")
                                  .setContext(getContext())
                                  .setCreateNewClientId(true)  // <-- new client!
                                  .setAvailabilityListener(new FeedAudioPlayer.availabilityListener() {
                                    public void onPlayerAvailable(FeedAudioPlayer player) {
                                      // here is your new client id
                                      String clientId = player.getClientId();

                                      // persist that ID somewhere
                                    }
                                    public void onPlayerUnavailable(Exception e) {
                                      // no client id for this person
                                    }
                                  })
                                  .build();

The example above will construct a new player that will immediately request a new client ID from the Feed.fm servers. The new client ID will be persisted to the local device and set as the default client ID for future players that don't request a new client ID or provide a client ID. The value can be retrieved via the FeedAudioPlayer.clientId method, and it should be stored

If your app has a previously generated client ID, then it can be provided to the player while constructing it, like so:

  FeedAudioPlayer player = new FeedAudioPlayer.Builder()
                                  .setToken("demo")
                                  .setSecret("demo")
                                  .setContext(getContext())
                                  .setClientId(previouslySaveClientId)  // <-- saved client id
                                  .setAvailabilityListener(new FeedAudioPlayer.availabilityListener() {
                                    public void onPlayerAvailable(FeedAudioPlayer player) {
                                      // player.getClientId() should match previouslySavedClientId
                                    }
                                    public void onPlayerUnavailable(Exception e) {
                                      // no client id for this person
                                    }
                                  })
                                  .build();