# Background sync on the next client (preview)

Canonical page: https://docs.ovok.com/native-sdk/guide/modules/next-background-sync

`@ovok/native/next/background-sync` exposes Android background task helpers and
cross-platform offline measurement scheduling for apps using `@ovok/core/next`.
It reuses the existing background-sync module and keeps its legacy import path
available.

Register a headless task with the host application's task manager, restore the
authenticated next client and patient, then run the Health Connect import:

```ts
import {
  registerAndroidHealthConnectBackgroundTask,
  runAndroidHealthConnectSync,
} from "@ovok/native/next/background-sync";

registerAndroidHealthConnectBackgroundTask(async () => {
  const { client, patientId } = await restoreHealthSyncSession();

  await runAndroidHealthConnectSync({ client, patientId, dataToSync });
});
```

Register the handler from the app entry point and restore the client and patient
inside it. The SDK checks that the restored session still belongs to `patientId`
before importing. See the
[full background-sync guide](/native-sdk/guide/modules/background-sync) for platform setup and the
[background-sync API reference](/native-sdk/reference/next-background-sync).

## Core offline measurement queue [#core-offline-measurement-queue]

Install the Expo task packages in the host app:

```sh
npx expo install expo-background-task expo-task-manager
```

Define the task from the app entry point so it is available when the OS starts a
fresh JavaScript runtime. Restore the client from the host app's secure session
storage inside the callback; the SDK never serializes credentials into task
input.

```ts
import {
  registerOfflineMeasurementBackgroundTask,
  scheduleOfflineMeasurementBackgroundSync,
  cancelOfflineMeasurementBackgroundSync,
} from "@ovok/native/next/background-sync";

registerOfflineMeasurementBackgroundTask(() => restoreOvokClient());

async function onBackgroundSyncEnabled() {
  await scheduleOfflineMeasurementBackgroundSync({
    minimumIntervalMinutes: 15,
  });
}

async function onBackgroundSyncDisabled() {
  await cancelOfflineMeasurementBackgroundSync();
}
```

The restored client must use the same durable storage, tenant, and API base;
Core scopes the queue to that owner and retains conditional creates and retry
state, so a restarted task can safely retry a queued measurement. Call
`cancelOfflineMeasurementBackgroundSync` to stop future runs.

WorkManager will not run more often than the 15-minute minimum. iOS uses
BGTaskScheduler and chooses its own execution time, which may be later than the
requested interval. Expo shares one background worker across registered tasks,
and the last registered task sets the worker's minimum interval. With Expo
Continuous Native Generation, prebuild adds iOS background processing
configuration; manually managed iOS apps must add Expo BackgroundTask's required
`UIBackgroundModes` and permitted task identifier to `Info.plist`.