getLastUpdate to poll your service for changes. The message has no input parameters. When content on your service changes, you should change the values in your response. The
getLastUpdate response has two different associated values, a catalog value and a favorites value. Both should return a string that indicates the current version of the resource in question for your service. Each time your service changes the string, change it to a new value that is never reused. See Synchronize your service for details.
||Boolean||(Optional) Enables the ability to disable automatic refresh of browse containers. Default is
||string||(Optional) A token that represents the current version of your global catalog. This should include all of the content that is not updated by users. For example, lists of albums and artists. You should change the
||string||(Optional) A token that represents user-specific content. This can include user likes, playlists, and the user’s personal library. It can also include content that changes with greater regularity than the catalog, such as recommendations. This can include content that users can update on Sonos apps or on the native app for your service.|
||int||(Optional) The length of time in seconds that the Sonos app should wait before polling the service with
Change the favorites value every time a user updates content
You should change the
favorites value every time a user updates content, such as when a user creates a playlist, deletes a playlist, adds a track to their favorites, removes a track from their favorites, or performs any playlist editing function. The following occurs when the user performs one of these types of operations:
- The Sonos app sends a
getLastUpdaterequest to your service.
- Your service sends back the current value for
- A user performs an action on their Sonos app that sends a message to your service, such as a REST request to add a favorite. See Add favorites for details.
- Your service responds to this request with a success response.
- After receiving your response, the Sonos app sends a
getLastUpdatemessage to your service.
- You should respond with a new
- This new
favoritesvalue triggers the Sonos app to refresh its user interface with a subsequent
getMetadataresponse will cause the changes to
favoritesto be reflected immediately on the specific Sonos app used.
Here’s a sequence diagram of what happens on a Sonos app when someone adds a new favorite:
Sonos apps send getLastUpdate requests at defined intervals
The Sonos app will also send a
getLastUpdate message at your defined polling interval to pick up other changes to user-generated content or your entire catalog. The user could change user-generated content outside of the Sonos app on your website or mobile app, or on a different Sonos app within the same Sonos system. Your global catalog changes when you push new content to all users.
If either the
favorites string value has changed, Sonos apps refresh their copies of the data for that resource. When these values change, this invalidates the caches on Sonos apps and allows the user interface to reflect the changes. A Sonos app only sends the periodic
getLastUpdate message to your service whenever a user is actively browsing your service or playing content from your service.
Keep in mind, this message is Sonos app-specific, so different Sonos apps attached to the same Sonos system may call
getLastUpdate at different times. The timing depends on when the user started interacting with your service. For example, if a family member favorites a track on your music service using the Sonos app on their Android phone, someone else in the household who is using the iOS Sonos app will see that change only after their Sonos app makes its periodic
If your server cluster processes
getMetadata messages for a single Sonos app during a single user session, it is essential that all servers that the Sonos app might hit synchronously reflect the same up-to-date
favorites values, and return consistent values for
getMetadata. Otherwise, the user interface on the Sonos app may fail to update or update continuously at each polling interval. For this reason, it may be preferable to associate a given user session to a particular server for the duration of that session.