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.10.4), the example app's Expo SDK 57 / React Native 0.86.3 toolchain,
and the public exports in src/index.tsx and src/modules/*/index.*. 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 runtime polyfills used by the mobile client.
The package has two import layers. The root import contains the shared application surface and Bluetooth management. Optional integrations are published as subpaths so an app can avoid loading unrelated native peers. The exact mapping is in the public API map.
@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 Ovok web API polyfills 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.
Choose a path
- Follow Quick start for the first working app shell.
- Follow Build an app with the SDK for the complete composition path from authentication through measurements, health import, forms, and background work.
- Use the how-to guides for a focused integration task.
- Use the App UI guide, Reusable flows, and component categories for UI integration.
- Use the SDK feature index to find a guide for every published module.
- Read Architecture and lifecycle when you need to understand provider ownership, native boundaries, or delivery guarantees.
End-to-end paths
| Path | Start here | Result |
|---|---|---|
| Login and app shell | App shell and authentication | Authenticated @ovok/core client and themed UI |
| Complete application path | Build an app with the SDK | A host-owned app composed from the SDK's runtime, auth, device, health, UI, and background surfaces |
| 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 |
| App UI | App UI guide | Component-by-component usage and shared theme behavior |
| CMS content and translations | CMS | Localized CMS data and translation loading |
| Progress indicators | Progress bar · Progress ring | Linear and circular indicators |
| Reusable UI flows | Reusable flows | Pairing, manual entry, and health-access integration examples |
| Custom BLE device | Bluetooth | Custom device declaration |
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.