Skip to main content

Background sync

Import background APIs from @ovok/native/background-sync. This module contains Android foreground-service controls, Android Health Connect scheduling, a secure storage adapter, and optional local-notification helpers.

import {
  createBackgroundSafeClientStorage,
  registerAndroidHealthConnectBackgroundTask,
  runAndroidHealthConnectSync,
  scheduleAndroidHealthConnectSync,
} from "@ovok/native/background-sync";

Android Bluetooth service​

Use AndroidBluetoothForegroundService when the app owns the BLE lifecycle outside BTProvider.backgroundSync, or call the imperative functions directly. The same module also exposes battery-optimization helpers:

import { AndroidBluetoothForegroundService } from "@ovok/native/background-sync";

<AndroidBluetoothForegroundService
  enabled={monitoring}
  options={{
    notificationTitle: "Bluetooth monitoring",
    notificationBody: "Listening for health measurements",
    requestBatteryOptimizationExemption: true,
  }}
>
  <BluetoothScreen />
</AndroidBluetoothForegroundService>;
import {
  isAndroidBatteryOptimizationIgnored,
  requestAndroidBatteryOptimizationExemption,
  startAndroidBluetoothForegroundService,
  stopAndroidBluetoothForegroundService,
} from "@ovok/native/background-sync";

const alreadyExempt = await isAndroidBatteryOptimizationIgnored();
if (!alreadyExempt) {
  await requestAndroidBatteryOptimizationExemption();
}

await startAndroidBluetoothForegroundService({
  notificationTitle: "Bluetooth monitoring",
});
await stopAndroidBluetoothForegroundService();

The imperative functions are no-ops on non-Android platforms. The foreground service functions and AndroidBluetoothForegroundService are alternatives for one BLE owner; do not run both for the same scan.

The service is Android-only. Its functions are safe to call on other platforms and return without starting a native service. Do not start the standalone service at the same time as the provider-owned service for the same scan.

Health Connect scheduling​

Register the headless task at app entry, then schedule work from a foreground screen:

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

registerAndroidHealthConnectBackgroundTask(async () => {
  const client = await restoreClient();
  await runAndroidHealthConnectSync({
    client,
    patientId: await restorePatientId(),
    dataToSync: androidDataToSync,
    onError: reportError,
  });
});

await scheduleAndroidHealthConnectSync({ intervalMinutes: 15 });

The minimum supported WorkManager interval is 15 minutes. Restore authentication and patient state inside the headless task; Android may recreate the process without a React tree. Call cancelAndroidHealthConnectSync when scheduled import is disabled. The optional taskName must match the name used during registration.

Background-safe client storage​

createBackgroundSafeClientStorage adapts a SecureStore-compatible implementation to the async storage interface expected by the client:

const storage = createBackgroundSafeClientStorage({
  secureStore,
  keychainService: "com.example.app",
  keychainAccessible: SecureStore.AFTER_FIRST_UNLOCK,
});

The adapter tracks its own key index and exposes getItem, setItem, removeItem, clear, and reload. A protected read that fails before first unlock does not delete the value; call reload after unlock and retry. The adapter does not own credentials, choose an application key, or authenticate the core client.

Local notifications​

getPushNotificationPermission, requestPushNotificationPermission, and showPushNotification load expo-notifications only when called. Install and configure that peer before using them. They create local notifications; they do not provide remote push tokens or background execution.

Native requirements​

Background APIs require a rebuilt native app. Configure the SDK Expo plugin with the matching Bluetooth, Health Connect, background, foreground-service, battery, and notification options before building. See Background sync for queue semantics, iOS restoration, Android permissions, and failure handling.