State Synchronization with Sync Objects

Twilio Sync relies on the concept of state synchronization. In this model, the authoritative state of your application exists in the cloud and is actively replicated - whether in whole or in part - to all of your users across all of your devices. The code you write is responsible for manipulating and representing this state: telling Sync when a customer is online/offline, their position on a website, etc.

Once your code relays this information, the Sync service does the rest, ensuring that your devices are always kept up to date in real-time, surviving connection failures and other network aberrations.

Sync Objects are the primitives you use to make your application's state discoverable and accessible at the right granularity. Sync provides four different object primitives to help.

• Documents A document is a single JSON object, up to 16kb in size. It is best suited to small use cases, such as basic publish/subscribe or where history synchronization is not a requirement.
• Lists A list maintains an ordered list of individual JSON objects, each up to 16kb in size. Use this object for more advanced use cases, such as synchronizing location data with the ability to replay old location states. Individual items are accessible through a system generated index.
• Maps A map maintains an unordered collection of developer specified keys and values. Use this object for synchronization cases where clients are interested in updates to individual keys, such as in presence use cases.
• Message Stream A stream lets you broadcast ephemeral JSON messages at a high rate to a group of subscribers.

These objects can be created via the REST API or by the relevant SDK. Every Document, List, Map and Stream is subject to rate limits. See our service limits page for details.

Because of rate limiting and access control, the Sync Object architecture of your application will have a significant impact on the scaling properties of the ultimate solution. As a guideline, favor more Sync objects (perhaps indexed in a separate, less-often updated map) to represent the unit in which your app scales. For example, consider one Map per user, not a single map for all users.

If you enable Access Control, the tokens you provide to your SDK-driven applications determine which objects your app can subscribe to or write. Be sure also to have a look at Securing your Sync App before you get too far.