'Hello, World!' Sync
Once you've set up your environment, try on Ditto and perform your first peer‑to‑peer sync.
Intended to get you oriented, this article provides a streamlined process for integrating sync functionality within your app.
If you prefer building and exploring through a task app, chat app, and so on, see Example Projects Overview.
Before you can begin syncing data offline, set up authentication and then start the sync process:
From the top-most scope of your app's codebase, add the following to set up authentication and start syncing offline.
Replace YOUR_APP_ID and YOUR_PLAYGROUND_TOKEN with your access credentials available from the portal. (See Sync Credentials)
Insert a document in your local Ditto store by calling the Execute API method on the store namespace with a local INSERT INTO query, specifying the document to insert.
For example, inserting a new document with a single field "color" set to "blue":
Establish a local listener, known as a store observer, for realtime monitoring and response to updates in your local Ditto store.
For example, you can set up a store observer to asynchronously display profile updates to end users when they modify their profiles.
To set up a store observer:
Call the Register Observer API method on the store namespace.
Include a local SELECT query specifying the document collection you want to watch and define a callback function to handle changes.
For example, watching documents from the cars collection in the Ditto store:
Please note that the observer must be kept in scope (i.e. as a property in a class) for as long as you wish to have your event handler be called when there is an update to a document matching the query you provide.
Register a remote listener, known as a sync subscription, by calling the Register Subscription API method on the sync namespace.
For example, creating a subscription to sync updates made to documents in the cars collection with color set to blue:
In Ditto, there is a clear distinction between traditional CREATE, READ, UPDATE, and DELETE (CRUD) database operations and data sync:
- To perform CRUD, you execute local data operations against store namespace.
- To perform sync, you execute remote data operations against the sync namespace.
To complete your understanding, the following graphic illustrates how sync subscriptions and store observers work together in practice:
Before you can sync offline, you must integrate sync functionality in your codebase. (See Integrating Sync Functionality)
Once integrated, you initiate a sync subscription request from your local Ditto store to remote peers. (See Creating Subscriptions)
The associated query specifying the data you want to watch then propagates to each end-user device connected within the mesh network:
When the data you've subscribed to changes on a remote peer — whether through insertions, updates, or deletions — the remote peer automatically syncs these delta changes to your local Ditto store over the mesh network:
Combining store observers with your sync subscriptions ensures that you receive updates from remote stores, enabling you to quickly respond in your app. (See Seetting Up Store Observers)
For more information, see any of the following: