# Reusable SDK features

Canonical page: https://docs.ovok.com/native-sdk/guide/sdk-features

The SDK exposes integration primitives and optional composition UI, not an application
workflow. A host can enable one supported device, register a custom device, or use the
complete catalog. Patient selection, authentication, server upload, storage,
notifications, and navigation remain host decisions; the optional `ui` module provides
themeable flows that accept the host's theme and primitive slots.

## Feature guides and API references [#feature-guides-and-api-references]

Use the guide to integrate a feature, then use its reference pages for component props,
types, and exported symbols.

| Feature | Guide | Reference |
| --- | --- | --- |
| Authentication | [Authentication](./modules/auth.md) | [Auth components](./components/auth/index.md) |
| Bluetooth measurements | [Bluetooth](./modules/bluetooth.md) | [Pairing flow](./components/ui/pairing-flow.md) · [Bluetooth state notice](./components/ui/bluetooth-state-notice.md) |
| HealthKit and Health Connect | [Health data](./modules/data-sync.md) | [Data sync](./components/data-sync/index.md) |
| Background delivery | [Background sync](./modules/background-sync.md) | [Background sync API](./components/background-sync/index.md) |
| App UI | [App UI guide](./modules/ui.md) | [UI components](./components/ui/index.md) |
| Reusable task flows | [Reusable flows](./how-to/reusable-flows.md) | [Flow components](./components/ui/reusable-flows/index.md) |
| Device catalog | [Supported devices](./supported-devices.md) | [Catalog list](./components/ui/supported-devices-catalog-list.md) |
| Guided breathing | [Breathing exercises](./modules/breathing-exercise.md) | [Breathing components](./components/breathing-exercise/index.md) |
| Content | [Content components](./modules/content.md) | [Cards, lists, and Composition detail](./components/content/index.md) |
| CMS content and translations | [CMS](./modules/cms.md) | [CMS hooks](./components/cms/index.md) |
| Diary cards | [Diary](./modules/diary.md) | [Diary components](./components/diary/index.md) |
| Journal prompts and entries | [Journal](./modules/journal.md) | [Journal components](./components/journal/index.md) |
| Language selection | [Language switcher](./modules/language-switcher.md) | [Switcher components and hook](./components/language-switcher/index.md) |
| Measurement lists | [Measurements](./modules/measurement.md) | [Measurement components](./components/measurement/index.md) |
| Observation detail | [Observation details](./modules/observation-detail.md) | [Observation detail components](./components/observation-detail/index.md) |
| Patient presentation | [Patient UI](./modules/patient.md) | [Patient components](./components/patient/index.md) |
| PDF rendering | [PDF viewer](./modules/pdf.md) | [PDFViewer](./components/pdf/index.md) |
| Selection sheets | [Picker sheets](./modules/picker-sheet.md) | [PickerSheet and WheelPicker](./components/picker-sheet/index.md) |
| Progress indicators | [Progress bars](./modules/progress-bar.md) · [Progress ring](./modules/progress-ring.md) | [ProgressBar](./components/progress-bar/index.md) · [ProgressRing](./components/progress-ring/index.md) |
| FHIR questionnaires | [Questionnaire forms](./modules/questionnaire-response-form.md) | [Form and advanced API](./components/questionnaire-response-form/index.md) |
| Settings screens | [Settings](./modules/setting.md) | [Setting components](./components/setting/index.md) |
| Real-time events | [Real-time sockets](./modules/socket.md) | [Socket provider and hooks](./components/socket/index.md) |
| In-screen tabs | [Tabs](./modules/tab.md) | [Tab components and provider](./components/tab/index.md) |
| Measurement tiles | [Tiles](./modules/tile.md) | [Tile components](./components/tile/index.md) |
| Ovok-hosted images | [Images](./modules/image.md) | [OptimizedImage](./components/optimized-image/index.md) |
| Form and UI helpers | [SDK helpers](./modules/helpers.md) | [Helpers](./components/helpers/index.md) |
| Logs and telemetry | [Observability](./how-to/observability.md) | [Logging](./components/helpers/logging.md) · [Telemetry](./components/helpers/telemetry.md) |
| Providers, polyfills, and theme | [App shell](./how-to/app-shell.md) | [Polyfills](./components/polyfills/index.md) · [Theme](./components/theme/index.md) |
| Public imports and types | [Public API map](./public-api.md) | Generated package and module export table |

## Bluetooth hooks [#bluetooth-hooks]

Render these hooks below `BluetoothProvider`:

```tsx
const { state, permission, requestPermission } = useBluetoothAdapter();
const { found } = useDiscovery({ vendor: "viatom" });
const paired = usePairedDevices();
const { snapshot, device } = useDevice(address);
const live = useLiveValues(address);
```

`useBluetoothAdapter` reports the radio state (`on`, `off`, `unauthorized`, `unsupported`
or `unknown`) and the permission. `useDiscovery` lists nearby devices and `bluetooth.pair(found)`
pairs one. The device hooks expose SDK events without prescribing how a host renders
them. Paired devices are kept by the store given to `createBluetooth`, so the SDK does
not need a storage key of its own.

Readings are saved through the `Ovok` client's outbox, which keeps each one on the device
until the server accepts it. A device's `record` setting turns saving of live streams on
or off, and the reading log reports each reading as `queued`, `saved` or `rejected`. See
[Bluetooth](./modules/bluetooth.md) for the snapshot, live values and the offline queue.

## Background sync and storage [#background-sync-and-storage]

A paired device set to `keepInBackground` stays connected, reconnects by its stored
address, and saves its readings through the outbox; see
[Bluetooth](./modules/bluetooth.md#syncing-by-itself). The Bluetooth layer has no separate
result queue to run or flush.

For credentials needed by a background relaunch, use
`createBackgroundSafeClientStorage` with an injected SecureStore-compatible adapter.
The exported `BackgroundSafeSecureStore`, `BackgroundSafeStorageOptions`, and
`BackgroundSafeClientStorage` types describe that boundary. Reads that fail before
first unlock never delete the stored value; call `reload` after unlock and retry.
The adapter does not own authentication or choose a host key. Test the supplied
adapter on each target OS: `keychainAccessible` is the numeric
`SecureStore.AFTER_FIRST_UNLOCK` value (the default is `0`), and secure-store writes
can still fail before native keychain setup or first unlock. On iOS, the current
`expo-secure-store` integration can reject the adapter's `AFTER_FIRST_UNLOCK` write
options, so writes may throw instead of becoming background-safe; verify that the
installed native version accepts the adapter's option shape before relying on writes
for a background relaunch. Surface write failures and provide a host-owned retry path.

The public boundary is intentionally small and app-owned:

```ts
interface BackgroundSafeSecureStore {
  getItemAsync(key: string, options?: Record<string, unknown>): Promise<string | null>;
  setItemAsync(key: string, value: string, options?: Record<string, unknown>): Promise<void>;
  deleteItemAsync?(key: string, options?: Record<string, unknown>): Promise<void>;
}

interface BackgroundSafeStorageOptions {
  secureStore: BackgroundSafeSecureStore;
  keyListKey?: string;
  keychainService?: string;
  keychainAccessible?: number;
}

interface BackgroundSafeClientStorage {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
  clear(): Promise<void>;
  reload(): Promise<void>;
}
```

## Health import [#health-import]

`useHealthImport` accepts a host-provided adapter for status and authorization. Its
`getStatus(type)` result is one of `authorized`, `shouldRequest`, `refused`, or
`unsupported`; `request(types, background)` receives the complete requested type list
and the hook-level background flag. The generic hook has no per-type `backgroundAccess`
field. Platform-specific Android background permission status belongs to
`DataSync.AndroidHealthConnectAuthorizationProvider`.

## Expo native setup [#expo-native-setup]

The optional `@ovok/native` config plugin only adds capabilities explicitly enabled by
the host:

```js
module.exports = [
  ["@ovok/native", {
    bluetooth: { background: true },
    healthKit: true,
    healthConnect: true,
    backgroundSync: true,
    notifications: false,
  }],
];
```

The plugin does not add the `expo-notifications` plugin unless `notifications: true`.
`bluetooth.background` enables iOS background-central configuration, while
`backgroundSync` enables the Android background service path. With `healthConnect:
true`, a truthy `backgroundSync` value also enables scheduled Health Connect work.
Inspect the merged native project. Native modules still require a development build;
Expo Go cannot load them.

## Test kit [#test-kit]

`createFakeBleManager` and `replayRecordedFrames` allow scan, parser, policy, and hook
tests to run without a peripheral. Apps can keep their own recorded fixture registry
with `defineRecordedDeviceFrames` and replay only the devices they support.

## Error contract [#error-contract]

Native failures can be normalized with `toBluetoothError`. The stable
`BluetoothErrorCode` is separate from the original error and optional translation key.
Existing measurement translation-key errors remain compatible with earlier callbacks.

## Release policy [#release-policy]

Behavior changes, new hooks, result identity changes, queue semantics, and native setup
changes are minor-release work. Patch releases are reserved for fixes that do not
change runtime behavior. A release that raises the required `@ovok/core` range must
release core first, then update the native peer range and package version.

## See also [#see-also]

- [Public API map](./public-api.md)
- [App UI](./modules/ui.md)
- [Architecture and lifecycle](./architecture.md)
