Skip to main content

Background sync APIs

The @ovok/native/background-sync subpath exports Android background controls, Health Connect headless task helpers, background-safe client storage, and local notification helpers. Import from this subpath so an app can use these APIs without loading the package's root UI barrel.

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

The full end-to-end setup, native configuration, and delivery behavior are in the background sync guide.

Android Bluetooth foreground service​

AndroidBluetoothForegroundService is a React wrapper for apps that own the BLE manager and scan lifecycle outside BTProvider:

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

<AndroidBluetoothForegroundService
  enabled={monitoring}
  options={{
    notificationTitle: "Bluetooth monitoring",
    notificationBody: "Listening for health measurements",
    requestBatteryOptimizationExemption: true,
  }}
  onError={({ error }) => reportBluetoothError(error)}
>
  <BluetoothScreen />
</AndroidBluetoothForegroundService>;
PropTypeDescription
enabledbooleanStarts the Android service while true; stops it on false or unmount.
optionsAndroidBluetoothForegroundServiceOptionsOptional notification title/body and battery-optimization request.
onError(event: ErrorCallback) => voidReceives service or permission request failures.
childrenReactNodeContent rendered inside the wrapper.

This component is an alternative to the provider-managed foreground service. Do not mount it for a scan already owned by BTProvider.backgroundSync; there should be one service owner per scan. On non-Android platforms the wrapper renders its children and does not start a native service.

The module also exports startAndroidBluetoothForegroundService and stopAndroidBluetoothForegroundService for imperative lifecycle control. These functions are Android-only and are no-ops on other platforms.

Android Health Connect headless work​

APIPurpose
registerAndroidHealthConnectBackgroundTask(task, taskName?)Register the JS entry point at app startup. The default task name is ANDROID_HEALTH_CONNECT_BACKGROUND_TASK.
runAndroidHealthConnectSync(options)Run one import without mounting AndroidHealthSync. Requires a restored client, patientId, and dataToSync mapping.
scheduleAndroidHealthConnectSync(options?)Schedule periodic WorkManager work. intervalMinutes defaults to 15 and values below 15 are raised to 15.
cancelAndroidHealthConnectSync()Cancel scheduled periodic work.
ANDROID_HEALTH_CONNECT_BACKGROUND_TASKDefault task name: OvokHealthConnectBackgroundSync.

The registered callback receives { reason?: string }. If scheduling uses a custom taskName, registration must use the same value. Calls are no-ops on non-Android platforms. WorkManager may defer execution and requires network connectivity.

AndroidHealthConnectBackgroundSyncOptions contains intervalMinutes, taskName, notificationTitle, and notificationBody. AndroidHealthConnectSyncRunOptions contains client, patientId, dataToSync, and optional chunkSize, onError, and onProgress. These types are exported from this subpath.

Use AndroidHealthSync for a foreground React import, and the Health Connect authorization provider to request foreground and optional background-read access.

Battery optimization helpers​

APIPurpose
isAndroidBatteryOptimizationIgnored()Read whether Android currently exempts the app from Doze optimizations.
requestAndroidBatteryOptimizationExemption()Open Android's consent/settings flow when it can be shown. The result can be false while consent is pending or has not been granted; re-check after the app resumes.

The request is explicit opt-in and does not grant an exemption itself. The helper returns true on non-Android platforms.

Background-safe client storage​

createBackgroundSafeClientStorage adapts a SecureStore-compatible implementation to the asynchronous storage shape used by OvokClient:

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

BackgroundSafeSecureStore requires getItemAsync and setItemAsync, with optional deleteItemAsync. The returned BackgroundSafeClientStorage exposes getItem, setItem, removeItem, clear, and reload. reload re-reads the adapter's key index after the device is unlocked. A protected read failure returns null without deleting the stored value; retry after the OS makes the keychain available.

The adapter does not choose an app key, own credentials, or restore an authenticated client. The host app remains responsible for that work in the Health Connect headless task.

Local notifications​

The subpath exports getPushNotificationPermission, requestPushNotificationPermission, and showPushNotification. They load the optional expo-notifications peer only when called. Permission status is "granted", "denied", or "undetermined". Request permission in the foreground.

showPushNotification schedules an immediate local notification. It does not create remote push tokens or schedule background execution. BLE queue notifications can instead be configured through BTProvider.backgroundSync.notifications; see the background sync guide.