Manage a Sync Session - Flutter SDK

Prerequisites

Before you can manage your sync session state, you must perform the following:

1. Configure Flexible Sync on the Atlas App Services backend

2. Add Device Sync to your app

Wait for Changes to Upload and Download

To asynchronously wait for all changes to upload to Atlas from your synced realm, call Session.waitForUpload(). To asynchronously wait for all changes on Atlas to download to your synced realm, call Session.waitForDownload().

// Wait to download all pending changes from Atlas
await realm.syncSession.waitForDownload();
// Add data locally
realm.write(() {
  realm.addAll<Car>([
    Car(ObjectId(), "Hyundai"),
    Car(ObjectId(), "Kia"),
    Car(ObjectId(), "Lincoln")
  ]);
});
// Wait for changes to upload to Atlas before continuing execution.
await realm.syncSession.waitForUpload();

You can add an optional CancellationToken to waitForUpload() and waitForDownload().

final cancellationToken = CancellationToken();
final waitForDownloadFuture =
    realm.syncSession.waitForDownload(cancellationToken);
cancellationToken.cancel();
final waitForUploadFuture =
    realm.syncSession.waitForUpload(cancellationToken);
cancellationToken.cancel();

Pause and Resume a Sync Session

To pause syncing for a session, call Session.pause(). The realm will not sync changes with Atlas while the session is paused.

To resume syncing a changes, call Session.resume().

You must manually call Session.pause() and Session.resume() for each realm whose Sync session you want to pause and restart. The sync state of one session has no impact on other open sessions.

The following code block demonstrates calling these methods:

// Pause the sync session
realm.syncSession.pause();
// Data that you add while the sync session is paused does not sync to Atlas.
// However, the data is still added to the realm locally.
realm.write(() {
  realm.addAll<Car>([
    Car(ObjectId(), "Volvo"),
    Car(ObjectId(), "Genesis"),
    Car(ObjectId(), "VW")
  ]);
});
// Resume sync session. Now, the data you wrote to the realm
// syncs to Atlas.
realm.syncSession.resume();

Monitor Sync Upload Progress

To monitor Sync upload progress progress, call SyncSession.getProgressStream(). This method returns a Stream of SyncProgress objects. SyncProgress provides the total number of transferrable bytes and the remaining bytes to be transferred.

SyncSession.getProgressStream() takes two arguments:

• A ProgressDirection enum that must be set to upload. This specifies that the progress stream tracks uploads.

• A ProgressMode enum that can be set to reportIndefinitely or forCurrentlyOutstandingWork. reportIndefinitely sets notifications to continue until the callback is unregistered. forCurrentlyOutstandingWork sets notifications to continue until only the currently-transferable bytes are synced.

final stream = realm.syncSession.getProgressStream(
    ProgressDirection.upload, ProgressMode.forCurrentlyOutstandingWork);
late StreamSubscription streamListener;
streamListener = stream.listen((syncProgressEvent) {
  if (syncProgressEvent.transferableBytes ==
      syncProgressEvent.transferredBytes) {
    // Upload complete
    print('Upload complete');
    // Stop listening to the Stream
    streamListener.cancel();
  }
});

Monitor Network Connection

You can get the state of the current network connection with Session.connectionState. This returns a ConnectionState enum that contains the network connection's state: connected, disconnected, or connecting.

if (realm.syncSession.connectionState == ConnectionState.connected) {
  // ... do stuff
}

Monitor the state of the network connection with Session.connectionStateChanges. This property returns a Stream of ConnectionStateChange objects that updates when the network connection changes. You can access the current and previous ConnectionState from ConnectionStateChange.

final connectionStream = realm.syncSession.connectionStateChanges;
late StreamSubscription streamListener;
streamListener = connectionStream.listen((connectionStateChange) {
  if (connectionStateChange.current == ConnectionState.connected) {
    print("Connected to Atlas Device Sync server");
    streamListener.cancel();
  }
});

Manually Reconnect All Sync Sessions

The Flutter SDK automatically detects when a device regains connectivity after being offline and attempts to reconnect using an incremental backoff strategy.

You can choose to manually trigger a reconnect attempt with the App.reconnect() instead of waiting for the duration of the incremental backoff. This is useful if you have a more accurate understanding of the network conditions and don't want to rely on automatic reconnect detection.

app.reconnect();

When you call this method, the SDK forces all sync sessions to attempt to reconnect immediately and resets any timers used for incremental backoff.