Manage a Sync Session - React Native SDK

Prerequisites

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

1. Open a synced realm

2. Add a sync subscription

3. Wrap components that use the useRealm() hook for a synced realm with the AppProvider, UserProvider, and RealmProvider components. For more information on configuring and opening a synced realm, refer to Open a Synced Realm.

Access Sync Session

Access a synced realm in a component with the useRealm() hook. Access the sync session with the realm's Realm.syncSession property.

import React, {useEffect} from 'react';
import {Context} from '../RealmConfig';
const {useRealm} = Context;
function AccessSyncSession() {
  const realm = useRealm();
  async function workWithSyncSession() {
    const {syncSession} = realm;
    // Do stuff with sync session...
  }
  // ...
}

Pause or Resume a Sync Session

Opening a synced realm starts a sync session. You can pause and resume the realm's sync session. If you have more than one open realm, pause does not affect the other realms' sync sessions.

To pause synchronization, use the Realm.syncSession.pause() method. To resume synchronization, use the Realm.syncSession.resume() method.

import React, {useEffect, useState} from 'react';
import {Context} from '../RealmConfig';
const {useRealm} = Context;
function ToggleSyncSession() {
  const realm = useRealm();
  const [isPaused, setIsPaused] = useState(false);
  async function toggleSyncSession() {
    if (isPaused) {
      await realm.syncSession?.resume();
    } else {
      await realm.syncSession?.pause();
    }
    setIsPaused(!isPaused);
  }
  return (
    <Button
      title={isPaused ? 'Pause Sync' : 'Unpause Sync'}
      onPress={toggleSyncSession}
    />
  );
}

Check Upload & Download Progress for a Sync Session

To check the upload and download progress for a sync session, add a progress notification using the Realm.syncSession.addProgressNotification() method.

The Realm.syncSession.addProgressNotification() method takes in the following three parameters:

• A direction parameter. Set to "upload" to register notifications for uploading data. Set to "download" to register notifications for downloading data.

• A mode parameter. Set to "reportIndefinitely" for the notifications to continue until the callback is unregistered using Realm.syncSession.removeProgressNotification(). Set to "forCurrentlyOutstandingWork" for the notifications to continue until only the currently transferable bytes are synced.

• A callback function parameter that has the arguments transferred and transferable. transferred is the current number of bytes already transferred. transferable is the total number of bytes already transferred plus the number of bytes pending transfer.

The following example registers a callback on the syncSession to listen for upload events indefinitely. The example writes to the realm and then unregisters the syncSession notification callback.

Check the Network Connection

Realm's offline-first design means that you generally don't need to check the current network connection state since data syncs in the background when a connection is available. That said, the Realm SDK provides methods to get the current state of the network connection to the server.

To check the current state of the connection to the server, call Realm.syncSession.isConnected(). This method returns a boolean that is true if there is a network connection and the sync session is active.

To listen for connection state changes, call Realm.syncSession.addConnectionNotification(), passing a callback function to handle network changes as the argument. To unregister the listener, pass the same callback function to Realm.syncSession.removeConnectionNotification().

Multiplex Sync Sessions

Enable session multiplexing to consolidate multiple sync sessions of a Realm app. Only use session multiplexing if you see errors about reaching the file descriptor limit, and you know you are using many sync sessions.

To enable session multiplexing, call Realm.App.Sync.enableSessionMultiplexing() with your Realm.App.

import React, {useEffect} from 'react';
import {Context} from '../RealmConfig';
import {AppProvider, UserProvider, useUser, useApp, Realm} from '@realm/react';
function AppWrapper() {
  return (
    <AppProvider id={APP_ID}>
      <UserProvider fallback={<LogIn />}>
        <RealmWrapper>
          <RestOfApp />
        </RealmWrapper>
      </UserProvider>
    </AppProvider>
  );
}
type RealmWrapperProps = {
  children: React.ReactNode;
};
function RealmWrapper({children}: RealmWrapperProps) {
  const app = useApp();
  Realm.App.Sync.enableSessionMultiplexing(app);
  return <RealmProvider sync={{flexible: true}}>{children}</RealmProvider>;
}