SDK guide
This is the source-of-truth integration guide for @ovok/native. It describes what the package exports, what the host app must configure, and how data moves from a native device or health platform into Ovok Core.
The guide is written against the repository's current package metadata (@ovok/native 1.5.6), the example app's Expo SDK 57 / React Native 0.86.3 toolchain, and the public exports in src/index.tsx. If a component page disagrees with this guide, verify the export and prop type in the repository before copying the example.
What belongs where
@ovok/native is the React Native and native-integration layer:
- UI components for authentication, patients, measurements, content, questionnaires, themes, navigation helpers, and health workflows.
- Bluetooth Low Energy discovery, device protocols, measurement decoding, and device UI.
- Apple HealthKit and Android Health Connect authorization and import components.
- Background Bluetooth and Health Connect orchestration.
- Expo/Medplum polyfills used by the mobile client.
@ovok/core owns the Ovok client, FHIR/authentication state, profile context, and the server-facing data model. A working app normally mounts OvokProvider from @ovok/core and ThemeProvider from @ovok/native.
Supported runtime shape
The repository example is a native Expo development build, not Expo Go. The SDK uses native modules for BLE, HealthKit, Health Connect, PDF rendering, permissions, and social sign-in. Adding the JavaScript package without rebuilding the native app is not enough.
The supported path in this repository is:
- Install @ovok/native and the peer dependencies for the features you use.
- Add the required Expo config plugins and platform permissions.
- Build a development or production binary.
- Initialize the Medplum web APIs before creating the app's Ovok provider.
- Mount the providers once at the app root.
- Add feature components below the providers.
Continue with installation, then app shell and providers.
End-to-end paths
| Path | Start here | Result |
|---|---|---|
| Login and app shell | App shell and authentication | Authenticated @ovok/core client and themed UI |
| Bluetooth measurement | Bluetooth and device catalog | Scan, connect, decode, and persist readings |
| BLE background delivery | Background sync | Durable at-least-once delivery with iOS restoration and Android foreground service support |
| Apple HealthKit | Health data | Authorized, incremental HealthKit import |
| Android Health Connect | Health data | Authorized, incremental Health Connect import and optional headless scheduling |
| UI library | UI modules | Component-by-component usage and existing detailed references |
| Custom BLE device | Bluetooth | A typed declaration that can be passed to BTProvider |
Important distinctions
- A display catalog entry is not automatically a Bluetooth declaration. Use SUPPORTED_DEVICES when you need both metadata and ready-to-use acceptedDevices.
- A supported device family is not a promise that every product sold under that brand uses the same advertisement name or wire protocol. The catalog records the exact names and declarations known to this SDK.
- Background work is OS-controlled. The SDK persists results and provides the native hooks, but iOS and Android can still defer or stop work according to system policy.
- Health permissions are separate from Ovok authentication. A signed-in user can still refuse individual HealthKit or Health Connect data types.