This article provides step-by-step instructions for setting up, maintaining, and ending data subscriptions for peer-to-peer asynchronous replication:
Expand to learn the basics of subscriptions
To set up a replication subscription in your app:
Syncing large documents can significantly impact sync performance:
Before you can set up your subscription listener, initiate the replication process in your app. Initiating replication indicates that you're ready receive updates from remote peers, as well as send updates to subscribing remote peers.
To initiate replication, early in your app lifecycle, such as within the following methods, call the startSync method
You must start replication (startSync) in the top-most scope to ensure that as soon as your app starts, it automatically connects with the mesh network and remains active throughout your app's lifecycle.
Otherwise, peer-to-peer connection may fail, resulting in remote peers becoming unable to send you updates in real-time.
In the top-most scope of your app, following the startSync method called in the previous step, set up a subscription object:
You must declare your subscription object from the top-most scope of your app to ensure access throughout your app.
Otherwise, you cannot modify or cancel your subscription from any part of your code, resulting in difficulty and potential errors when managing the subscription's lifecycle.
- Pass your replication query as an argument to find.
- Call thesubscribe method, and then pass the subsequent actions and processes you want to execute when your criteria is met as an argument.
Once you've set up your subscription, your subscription query is automatically sent to all peers connected in the mesh network. If there are any data changes that match your criteria, Ditto automatically triggers your subscribe callback function that performs followup actions and processes in your app.
For example, the following snippet demonstrates how to establish a carsSubscription to listen for all updates to documents in the "cars" collection with a field of color set to the value "blue":
In order to prevent memory leaks, Ditto's built-in memory management mechanisms automatically cancels active subscriptions that are no longer needed or relevant.
Therefore, if you store the subscription object at a local scope within your code, once Ditto executes your subscribe callback function, the subscription object may be removed from memory leading to unexpected behaviors.
To cancel a subscription, callcancel on the subscription object you set up to establish your subscription.
For example, continuing with the previous example, the following snippet illustrates canceling the carsSubscription: