# @ovok/native/background-sync

Canonical page: https://docs.ovok.com/native-sdk/reference/background-sync

Android background sync, the Bluetooth foreground service, sync notifications and background-safe storage.

Import from `@ovok/native/background-sync`.

## Components [#components]

### AndroidBluetoothForegroundService() [#androidbluetoothforegroundservice]

```ts
function AndroidBluetoothForegroundService(__namedParameters): Element;
```

Keeps the Android Bluetooth foreground service running while `enabled` is true.

#### Parameters [#parameters]

| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | `AndroidBluetoothForegroundServiceProps` |

#### Returns [#returns]

`Element`

## Functions [#functions]

### cancelAndroidHealthConnectSync() [#cancelandroidhealthconnectsync]

```ts
function cancelAndroidHealthConnectSync(): Promise<void>;
```

Cancels the scheduled Health Connect sync.

#### Returns [#returns-1]

`Promise`\<`void`\>

***

### createBackgroundSafeClientStorage() [#createbackgroundsafeclientstorage]

```ts
function createBackgroundSafeClientStorage(__namedParameters): BackgroundSafeClientStorage;
```

Creates a storage adapter without importing expo-secure-store at module load time.

#### Parameters [#parameters-1]

| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | [`BackgroundSafeStorageOptions`](#backgroundsafestorageoptions) |

#### Returns [#returns-2]

[`BackgroundSafeClientStorage`](#backgroundsafeclientstorage)

***

### getPushNotificationPermission() [#getpushnotificationpermission]

```ts
function getPushNotificationPermission(): Promise<PushNotificationPermissionStatus>;
```

Reads the current notification permission without showing a prompt.

#### Returns [#returns-3]

`Promise`\<[`PushNotificationPermissionStatus`](#pushnotificationpermissionstatus)\>

***

### isAndroidBatteryOptimizationIgnored() [#isandroidbatteryoptimizationignored]

```ts
function isAndroidBatteryOptimizationIgnored(): Promise<boolean>;
```

Returns whether Android currently exempts the app from Doze battery optimizations.

#### Returns [#returns-4]

`Promise`\<`boolean`\>

***

### registerAndroidHealthConnectBackgroundTask() [#registerandroidhealthconnectbackgroundtask]

```ts
function registerAndroidHealthConnectBackgroundTask(task, taskName?): void;
```

Registers the JS entry point WorkManager invokes after process death. Call
this once from the app entry point, not from a screen component, so it is
registered before Android wakes the headless runtime.

#### Parameters [#parameters-2]

| Parameter | Type | Default value |
| ------ | ------ | ------ |
| `task` | [`AndroidHealthConnectBackgroundTask`](#androidhealthconnectbackgroundtask) | `undefined` |
| `taskName?` | `string` | `ANDROID_HEALTH_CONNECT_BACKGROUND_TASK` |

#### Returns [#returns-5]

`void`

***

### requestAndroidBatteryOptimizationExemption() [#requestandroidbatteryoptimizationexemption]

```ts
function requestAndroidBatteryOptimizationExemption(): Promise<boolean>;
```

Opens Android's consent screen for a Doze exemption. This is always explicit
opt-in. A false result means the exemption is not active yet; it can also
mean the app is not currently foregrounded, the user has already answered,
or the prompt was already shown. Recheck
`isAndroidBatteryOptimizationIgnored` after returning to the foreground.

#### Returns [#returns-6]

`Promise`\<`boolean`\>

***

### requestPushNotificationPermission() [#requestpushnotificationpermission]

```ts
function requestPushNotificationPermission(): Promise<PushNotificationPermissionStatus>;
```

Requests notification permission. Call this while the app is in the foreground.

#### Returns [#returns-7]

`Promise`\<[`PushNotificationPermissionStatus`](#pushnotificationpermissionstatus)\>

***

### runAndroidHealthConnectSync() [#runandroidhealthconnectsync]

```ts
function runAndroidHealthConnectSync(__namedParameters): Promise<void>;
```

Runs one Health Connect import without mounting React components.

Headless JS tasks have no React tree, so AndroidHealthSync cannot be rendered
after the OS recreates the app process. The host app still restores its own
client and patient identity, then calls this function with the same mapping
it uses in the foreground.

#### Parameters [#parameters-3]

| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | [`AndroidHealthConnectSyncRunOptions`](#androidhealthconnectsyncrunoptions) |

#### Returns [#returns-8]

`Promise`\<`void`\>

***

### scheduleAndroidHealthConnectSync() [#scheduleandroidhealthconnectsync]

```ts
function scheduleAndroidHealthConnectSync(options?): Promise<void>;
```

Schedules a WorkManager wake-up that starts the registered headless JS task.
The task must create the host app's authenticated client and run the desired
AndroidHealthSync service; the SDK cannot serialize a client or auth token.

#### Parameters [#parameters-4]

| Parameter | Type |
| ------ | ------ |
| `options?` | [`AndroidHealthConnectBackgroundSyncOptions`](#androidhealthconnectbackgroundsyncoptions) |

#### Returns [#returns-9]

`Promise`\<`void`\>

***

### showPushNotification() [#showpushnotification]

```ts
function showPushNotification(__namedParameters): Promise<void>;
```

Shows a local notification for a measurement delivered by the background queue.

#### Parameters [#parameters-5]

| Parameter | Type |
| ------ | ------ |
| `__namedParameters` | [`PushNotificationContent`](#pushnotificationcontent) |

#### Returns [#returns-10]

`Promise`\<`void`\>

***

### startAndroidBluetoothForegroundService() [#startandroidbluetoothforegroundservice]

```ts
function startAndroidBluetoothForegroundService(options?): Promise<void>;
```

Starts the Android connected-device foreground service. Mount this alongside
the BTProvider that owns the scan; the service keeps that app process alive
while Android has the app in the background.

#### Parameters [#parameters-6]

| Parameter | Type |
| ------ | ------ |
| `options?` | [`AndroidBluetoothForegroundServiceOptions`](#androidbluetoothforegroundserviceoptions) |

#### Returns [#returns-11]

`Promise`\<`void`\>

***

### stopAndroidBluetoothForegroundService() [#stopandroidbluetoothforegroundservice]

```ts
function stopAndroidBluetoothForegroundService(): Promise<void>;
```

Stops the Android Bluetooth foreground service.

#### Returns [#returns-12]

`Promise`\<`void`\>

## Interfaces [#interfaces]

### AndroidBluetoothForegroundServiceOptions [#androidbluetoothforegroundserviceoptions]

Options of the Android Bluetooth foreground service.

#### Properties [#properties]

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="property-notificationbody"></a> `notificationBody?` | `string` | Text of the service notification body. |
| <a id="property-notificationtitle"></a> `notificationTitle?` | `string` | Text shown while the service keeps the BLE scan alive. |
| <a id="property-requestbatteryoptimizationexemption"></a> `requestBatteryOptimizationExemption?` | `boolean` | Ask Android to exempt this app from Doze when the service starts or returns to the foreground. |

***

### AndroidHealthConnectBackgroundSyncOptions [#androidhealthconnectbackgroundsyncoptions]

Options of the scheduled Health Connect sync.

#### Properties [#properties-1]

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="property-intervalminutes"></a> `intervalMinutes?` | `number` | WorkManager's minimum supported interval is 15 minutes. |
| <a id="property-notificationbody-1"></a> `notificationBody?` | `string` | Text of the sync notification body. |
| <a id="property-notificationtitle-1"></a> `notificationTitle?` | `string` | Title of the sync notification. |
| <a id="property-taskname"></a> `taskName?` | `string` | Must match the task name registered with `register...Task`. |

***

### BackgroundSafeClientStorage [#backgroundsafeclientstorage]

Async key-value storage backed by a SecureStore-compatible store.

#### Properties [#properties-2]

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="property-clear"></a> `clear` | () => `Promise`\<`void`\> | Removes every key recorded in the index. |
| <a id="property-getitem"></a> `getItem` | (`key`) => `Promise`\<`string` \| `null`\> | Returns the stored value, or `null` when absent or unreadable. |
| <a id="property-reload"></a> `reload` | () => `Promise`\<`void`\> | Re-reads the key index after the device has completed first unlock. |
| <a id="property-removeitem"></a> `removeItem` | (`key`) => `Promise`\<`void`\> | Removes `key` and drops it from the index. |
| <a id="property-setitem"></a> `setItem` | (`key`, `value`) => `Promise`\<`void`\> | Stores `value` under `key` and records the key in the index. |

***

### BackgroundSafeSecureStore [#backgroundsafesecurestore]

A small storage adapter for values needed by a background relaunch.

The SDK deliberately does not own authentication or choose an app key. The host
supplies a SecureStore-compatible implementation and may use this adapter for a
session token, refresh token, or any other background-safe value.

#### Properties [#properties-3]

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="property-deleteitemasync"></a> `deleteItemAsync?` | (`key`, `options?`) => `Promise`\<`void`\> | Deletes the value under `key`; when omitted, removals only update the key index. |
| <a id="property-getitemasync"></a> `getItemAsync` | (`key`, `options?`) => `Promise`\<`string` \| `null`\> | Reads the value stored under `key`, or `null` when absent. |
| <a id="property-setitemasync"></a> `setItemAsync` | (`key`, `value`, `options?`) => `Promise`\<`void`\> | Stores `value` under `key`. |

***

### BackgroundSafeStorageOptions [#backgroundsafestorageoptions]

Options for [createBackgroundSafeClientStorage](#createbackgroundsafeclientstorage).

#### Properties [#properties-4]

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="property-keychainaccessible"></a> `keychainAccessible?` | `number` | Expo SecureStore.AFTER_FIRST_UNLOCK is numeric; pass that host constant when available. |
| <a id="property-keychainservice"></a> `keychainService?` | `string` | Keychain service name passed to the secure store on every call. |
| <a id="property-keylistkey"></a> `keyListKey?` | `string` | Used only for the adapter's internal key index; no application identity is assumed. |
| <a id="property-securestore"></a> `secureStore` | [`BackgroundSafeSecureStore`](#backgroundsafesecurestore) | SecureStore-compatible store that persists the values. |

***

### PushNotificationContent [#pushnotificationcontent]

Content of a local notification.

#### Properties [#properties-5]

| Property | Type | Description |
| ------ | ------ | ------ |
| <a id="property-body"></a> `body?` | `string` | Notification body text. |
| <a id="property-data"></a> `data?` | `Record`\<`string`, `string` \| `number` \| `boolean` \| `null`\> | Extra data delivered with the notification. |
| <a id="property-title"></a> `title` | `string` | Notification title. |

## Type Aliases [#type-aliases]

### AndroidHealthConnectBackgroundTask [#androidhealthconnectbackgroundtask]

```ts
type AndroidHealthConnectBackgroundTask = (input) => Promise<void>;
```

Headless task invoked when the scheduled sync wakes the app.

#### Parameters [#parameters-7]

| Parameter | Type |
| ------ | ------ |
| `input` | \{ `reason?`: `string`; \} |
| `input.reason?` | `string` |

#### Returns [#returns-13]

`Promise`\<`void`\>

***

### AndroidHealthConnectSyncRunOptions [#androidhealthconnectsyncrunoptions]

```ts
type AndroidHealthConnectSyncRunOptions = object;
```

Options of `runAndroidHealthConnectSync`.

#### Properties [#properties-6]

##### chunkSize? [#chunksize]

```ts
chunkSize?: number;
```

Number of records sent per request.

##### client [#client]

```ts
client: Ovok;
```

A restored, authenticated core client.

##### dataToSync [#datatosync]

```ts
dataToSync: AndroidHealthSyncProps["dataToSync"];
```

The same record-to-Observation mapping used by AndroidHealthSync.

##### onError? [#onerror]

```ts
onError?: (error) => void;
```

Called when the import fails.

###### Parameters [#parameters-8]

| Parameter | Type |
| ------ | ------ |
| `error` | `Error` |

###### Returns [#returns-14]

`void`

##### onProgress? [#onprogress]

```ts
onProgress?: (progress) => void;
```

Called with the per-type sync progress.

###### Parameters [#parameters-9]

| Parameter | Type |
| ------ | ------ |
| `progress` | `Partial`\<`Record`\<[`HealthSyncKey`](/native-sdk/reference/data-sync#healthsynckey), [`SyncProgress`](/native-sdk/reference/data-sync#syncprogress)\>\> |

###### Returns [#returns-15]

`void`

##### patientId [#patientid]

```ts
patientId: string;
```

The patient whose Health Connect records should be imported.

***

### PushNotificationPermissionStatus [#pushnotificationpermissionstatus]

```ts
type PushNotificationPermissionStatus = "granted" | "denied" | "undetermined";
```

Notification permission state.

## Variables [#variables]

### ANDROID\_HEALTH\_CONNECT\_BACKGROUND\_TASK [#android_health_connect_background_task]

```ts
const ANDROID_HEALTH_CONNECT_BACKGROUND_TASK: "OvokHealthConnectBackgroundSync" = "OvokHealthConnectBackgroundSync";
```

Default name of the headless task that runs the Health Connect sync.