Synchronize your service

The Sonos app polls your service with getLastUpdate requests to coordinate synchronization between Sonos and your service. Use responses to getLastUpdate link to manage the following aspects of synchronization:

• Catalog changes: Indicate when you've updated or changed the global catalog for your service. A global catalog change should include all of the content that is not updated by users. For example, lists of albums, artists, tracks, and radio streams.
• User-specific changes: Indicate when a listener made changes, for example, by liking a song or updating a playlist or their personal library.
• Polling interval: Reset the polling interval that the Sonos app uses for the time between calls to getLastUpdate.

Sonos uses your getLastUpdate responses to manage refreshing its data caches. A Sonos app only sends the periodic getLastUpdate request to your service whenever a listener is actively browsing your service or playing content from your service. When your response indicates changes, this invalidates the caches on Sonos apps and allows the user interface to reflect the changes. For example, when you indicate your catalog changed, the Sonos app will send getMetadata requests to the service for updates rather than use the cached data it might already have.

Keep in mind that the getLastUpdate response is specific to a given Sonos app. Therefore, different Sonos apps attached to the same Sonos system will likely 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 getLastUpdate call.

⚠️

If your implementation uses a server cluster

Consider isolating processing of a specific user session to one server for the duration of that session.

If your implementation might handle each SMAPI request on a different server each time, then all the cluster servers will have to synchronously reflect the same changes for a single Sonos app during a single user session. Otherwise, the user interface on the Sonos app may fail to update from getMetadata requests or may update continuously at each polling interval.

Synchronizing global catalog changes

To let Sonos know when your catalog has changed, use the catalog string value in your getLastUpdate response. A new string value represents the new version of your global catalog.

You should change the catalog value whenever you update your global catalog, such as once a day during a daily content change. Do not change your catalog value too frequently or your service will potentially get too many getMetadata requests from many possible users.

The getLastUpdate request has no parameters as follows:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <getLastUpdate xmlns="http://www.sonos.com/Services/1.1">
    </getLastUpdate>
  </soap:Body>
</soap:Envelope

A getLastUpdate response to tell Sonos to update your catalog might look like the following, where the string for catalog is different from the previous value used.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <getLastUpdateResponse xmlns="http://www.sonos.com/Services/1.1">
      <getLastUpdateResult>
        <catalog>1235</catalog>
      </getLastUpdateResult>
    </getLastUpdateResponse>
  </soap:Body>
</soap:Envelope>

Synchronizing user-specific changes

To let Sonos know about a user's changes, use the favorites string value in your getLastUpdate response. A new value indicates that changes have occurred to this user's data. You use the favorites string to represent not only changes to the user's favorites, but also for changes to the user's likes, playlists, and the user's personal library. You can add user-specific features such as favorites and playlists. See Adding Content Service features for details.

You can also use favorites to inform Sonos about content that changes with greater regularity than the entire catalog, such as user recommendations.

The following is a getLastUpdate request:

<soap:Envelope xmlns:soap="<http://schemas.xmlsoap.org/soap/envelope/">>  
  <soap:Body>  
   <getLastUpdate xmlns="http://www.sonos.com/Services/1.1">  
   </getLastUpdate>  
  </soap:Body>  
</soap:Envelope

A getLastUpdate response to tell Sonos to update user-specific data might look like the following, where the string for favorites is different from the previous value used.

<soap:Envelope xmlns:soap="<http://schemas.xmlsoap.org/soap/envelope/">>  
  <soap:Body>  
   <getLastUpdateResponse xmlns="http://www.sonos.com/Services/1.1">  
     <getLastUpdateResult>  
       <favorites>4321</favorites>  
     </getLastUpdateResult>  
   </getLastUpdateResponse>  
  </soap:Body>  
</soap:Envelope>

Make sure changes made via Sonos show up quickly in any other client interfaces you have and vice versa. For example, when a user favorites a track in your mobile app, their Sonos apps should see it in close to real time. Conversely, if a user dislikes a track in the Sonos app, it should be marked as disliked in your other interfaces and treated accordingly. Use getLastUpdate to help manage this process.

Setting the polling interval for getLastUpdate

When you submit your service you initialize the polling interval that the Sonos app uses for getLastUpdate See submit your content service for details. You also initialize the polling interval when testing your integration. See test your content service for details.

If you wish to change the polling interval on-the-fly, set the pollInterval value to a number of seconds in your response to getLastUpdate. For example:

<soap:Envelope xmlns:soap="<http://schemas.xmlsoap.org/soap/envelope/">>  
  <soap:Body>  
   <getLastUpdateResponse xmlns="http://www.sonos.com/Services/1.1">  
     <getLastUpdateResult>  
       <favorites>4321</favorites>  
       <catalog>1234</catalog>  
       <pollInterval>120</pollInterval>  
     </getLastUpdateResult>  
   </getLastUpdateResponse>  
  </soap:Body>  
</soap:Envelope>