Reusable SDK features

The SDK exposes integration primitives and optional composition UI, not an application workflow.

  • Stable unknown
  • Release candidate since 1.16.1-rc.1
  • Development since 1.16.1-dev+97b2473

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

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

FeatureGuideReference
AuthenticationAuthenticationAuth components
Bluetooth measurementsBluetoothPairing flow · Bluetooth state notice
HealthKit and Health ConnectHealth dataData sync
Background deliveryBackground syncBackground sync API
App UIApp UI guideUI components
Reusable task flowsReusable flowsFlow components
Device catalogSupported devicesCatalog list
Guided breathingBreathing exercisesBreathing components
ContentContent componentsCards, lists, and Composition detail
CMS content and translationsCMSCMS hooks
Diary cardsDiaryDiary components
Journal prompts and entriesJournalJournal components
Language selectionLanguage switcherSwitcher components and hook
Measurement listsMeasurementsMeasurement components
Observation detailObservation detailsObservation detail components
Patient presentationPatient UIPatient components
PDF renderingPDF viewerPDFViewer
Selection sheetsPicker sheetsPickerSheet and WheelPicker
Progress indicatorsProgress bars · Progress ringProgressBar · ProgressRing
FHIR questionnairesQuestionnaire formsForm and advanced API
Settings screensSettingsSetting components
Real-time eventsReal-time socketsSocket provider and hooks
In-screen tabsTabsTab components and provider
Measurement tilesTilesTile components
Ovok-hosted imagesImagesOptimizedImage
Form and UI helpersSDK helpersHelpers
Logs and telemetryObservabilityLogging · Telemetry
Providers, polyfills, and themeApp shellPolyfills · Theme
Public imports and typesPublic API mapGenerated package and module export table

Bluetooth hooks

Render these hooks below BluetoothProvider:

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 for the snapshot, live values and the offline queue.

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. 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:

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

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

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

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

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

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

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

Last updated on

On this page