Installation and native setup

This guide covers the package, its peer dependencies, and the native configuration needed by each feature. It targets Expo projects using Prebuild or EAS Build, as in the repository example. A full @ovok/native app needs a native development build; Expo Go does not contain all of the SDK's native modules.

Compatibility baseline

The repository example currently uses:

Platform	Example baseline
Expo	SDK 57
React Native	0.86.3
React	19.2.3
Android	Minimum SDK 26
iOS	Deployment target 16.4 in the example app

These are the example app's settings, not a promise that every combination of Expo and React Native works. Match the native peer packages to your app's Expo SDK. Use npx expo install for Expo and React Native packages so Expo can select compatible versions. The package's exact peer ranges are declared in the root package.json.

Install the package

Install the SDK and its OVOK client:

npm install @ovok/native @ovok/core

With Yarn, use yarn add @ovok/native @ovok/core instead.

The required peer dependencies in @ovok/native are @ovok/core (version 0.4.27 or newer), react, react-native, react-native-ble-plx, and react-native-permissions. An Expo project already has React and React Native; install the native peers using Expo's installer:

npx expo install react-native-ble-plx react-native-permissions

Install optional peer packages only for the features your app imports. For example, add Expo crypto and secure storage when a feature uses them:

npx expo install expo-crypto expo-secure-store

The feature matrix below groups the optional peers declared by the package. Treat it as a selection guide; package.json is the version-range source of truth.

Feature	Optional peer packages
Core UI	@expo-google-fonts/dm-sans, @gorhom/bottom-sheet, react-native-gesture-handler, react-native-reanimated, react-native-safe-area-context, react-native-keyboard-controller, react-native-paper, react-native-svg
Authentication	@react-native-google-signin/google-signin, expo-apple-authentication, expo-web-browser, formik, yup, i18next, react-i18next, iconsax-react-nativejs
HealthKit	@kingstinct/react-native-healthkit
Health Connect	expo-health-connect, react-native-health-connect
Network-aware import	@react-native-community/netinfo
Media and forms	expo-image, expo-linear-gradient, lottie-react-native, @react-native-community/datetimepicker, react-native-modal-datetime-picker, react-native-element-dropdown, @shopify/flash-list, date-fns, react-native-render-html
PDFs and files	react-native-pdf, react-native-blob-util
Crypto and storage	expo-crypto, expo-secure-store, expo-standard-web-crypto
Sockets and telemetry	socket.io-client, @opentelemetry/api, @opentelemetry/api-logs
Expo config plugin	@expo/config-plugins (provided by Expo in an Expo app)
Background notifications	expo-notifications
Background persistence	An app-owned durable store implementing `getItem` and `setItem`

The package root exports shared UI, authentication, and Bluetooth-management APIs. Optional integrations such as Health Connect, PDF, sockets, and background sync are available through public subpaths. Import them from the path listed in the Public API map and install peers for the APIs you use; this keeps unrelated native modules out of the import graph.

Configure Expo native capabilities

Installing @ovok/native does not add permissions or enable background services. The SDK provides an opt-in Expo config plugin for Bluetooth, HealthKit, Health Connect, background services, and notifications. Add it to the plugins array in app.config.ts or app.json only for capabilities your app uses. Expo applies config plugins during Prebuild or EAS Build; changing app config requires a new native build. See Expo config plugins.

For example, this enables Bluetooth background support:

plugins: [
  [
    "@ovok/native",
    {
      bluetooth: {
        background: true,
        bluetoothAlwaysPermission:
          "Allow $(PRODUCT_NAME) to connect to health devices",
      },
    },
  ],
]

The snippet is a plugins array entry, not a complete app config. Add other options only when the app needs them:

Option	Native setup it enables
`bluetooth`	Composes the `react-native-ble-plx` plugin, sets the iOS Bluetooth usage description, and adds Android scan/connect permissions. Set `background: true` for iOS background-central mode and the Android connected-device service path.
`healthKit`	Composes the HealthKit plugin and adds the HealthKit entitlement. Set `{ background: true }` when using HealthKit background delivery. Add the app-specific iOS usage descriptions yourself.
`healthConnect`	Composes the `expo-health-connect` plugin. Declare Android read/write permissions for the record types your app requests.
`backgroundSync`	Enables Android background service configuration. For BLE, set `backgroundSync.android.foregroundService` when using the provider-managed service. For Health Connect scheduling, set `healthConnect` and a truthy `backgroundSync`. See Background sync.
`notifications`	Composes the `expo-notifications` plugin. Enable it only when the app uses notifications.

backgroundSync.android.foregroundService.requestBatteryOptimizationExemption adds the Android permission that allows the SDK to ask for battery-optimization consent. It does not grant the exemption. The user still makes that choice in Android settings.

The repository example configures some third-party plugins directly in example/app.config.ts. The SDK plugin is a convenience for the capabilities above; for each native feature, keep its plugin configuration in one place and add any options that the wrapper does not manage directly.

iOS setup

Add only the capabilities the app uses:

Bluetooth: include a clear NSBluetoothAlwaysUsageDescription. The SDK plugin's bluetoothAlwaysPermission option sets it. Set bluetooth.background: true only when using background central restoration.
HealthKit: enable the HealthKit capability and set NSHealthShareUsageDescription and NSHealthUpdateUsageDescription in the app config. Set healthKit: { background: true } when using AppleHealthSync with backgroundDelivery.
Apple Sign-In: add expo-apple-authentication to the plugin list and set ios.usesAppleSignIn: true.
Google Sign-In: add the Google Sign-In config plugin and provide its iOS URL scheme.

Use explanations that match your app's actual data use. Do not copy the example app's bundle identifiers, OAuth client IDs, or usage text. Test Bluetooth, HealthKit, and social sign-in on physical iOS hardware.

For HealthKit, add app-specific usage text in app.config.ts:

ios: {
  infoPlist: {
    NSHealthShareUsageDescription:
      "Explain why this app reads the selected health data.",
    NSHealthUpdateUsageDescription:
      "Explain why this app writes the selected health data.",
  },
},

Android setup

Bluetooth: request only the Bluetooth permissions required for the app's scan and connection flow. The SDK plugin adds scan/connect permissions when bluetooth is enabled. Background BLE also needs the Android foreground service path.
Health Connect: declare the android.permission.health.READ_* and WRITE_* permissions that match the record types in your dataToSync configuration. Do not copy the full example list if your app imports fewer types. For background reads, request Health Connect background access and enable the matching background service configuration.
Notifications: Android may require notification permission at runtime for background notifications. Add the notification plugin and request permission through your app's notification flow.

For example, if the app reads and writes weight, add only those record permissions to android.permissions in app.config.ts:

android: {
  permissions: [
    "android.permission.health.READ_WEIGHT",
    "android.permission.health.WRITE_WEIGHT",
  ],
},

Add the matching permissions for every record type in dataToSync. When using the SDK plugin for Health Connect background work, it adds READ_HEALTH_DATA_IN_BACKGROUND and the required service declarations; when configuring native projects directly, add the equivalent permission and service setup yourself.

The SDK/plugin adds foreground-service declarations for the background features it configures. If you manage native configuration yourself, preserve the corresponding service types and permissions. See Android's Health Connect setup for the current platform requirements. Health Connect requires Android 9 (API 28) or newer with Google Play services; on Android 13 and earlier, users install the Health Connect app from Google Play.

Build a development app

Install Expo's development client, apply the native configuration, and build for the platform you use:

npx expo install expo-dev-client
npx expo prebuild
npx expo run:ios

For Android, use:

npx expo run:android

The first native build includes the installed native modules and config plugins. Start Metro against that build with npx expo start --dev-client. For local builds, run Prebuild and rebuild after adding a native dependency or changing a config plugin; EAS Build applies the app config as part of its native build. JavaScript-only changes can be loaded from Metro without rebuilding. See Expo's development build guide for the dev-client workflow.

Avoid npx expo prebuild --clean unless you intentionally want Expo to regenerate the native projects. Review native project changes before committing them.

Initialize the OVOK client

Initialize the native runtime once from the app entry module before importing the app or other SDK modules. See Polyfills and runtime setup for the bootstrap example. The client module can then create OvokClient:

import { OvokClient, OvokProvider } from "@ovok/core";
import { ExpoClientStorage } from "@ovok/native";

const client = new OvokClient({
  storage: new ExpoClientStorage(),
  baseUrl: process.env.EXPO_PUBLIC_OVOK_BASE_URL,
  fhirUrlPath: "/fhir",
});

Mount OvokProvider near the app root. The Quick start shows a complete app shell and sign-in route. The package also exports cleanupOvokNativeRuntime, ExtendedExpoCrypto, and initWebSocketManager for explicit cleanup, crypto, and WebSocket setup.

Check the native configuration

Before testing a feature, inspect the resolved Expo config and check Expo package compatibility:

npx expo config --type public
npx expo install --check

Then build the platform you ship and verify that the generated iOS Info.plist/entitlements or Android manifest contain only the permissions and services required by the enabled features. Test Bluetooth and health integrations on physical hardware.

Compatibility baseline​

Install the package​

Configure Expo native capabilities​

iOS setup​

Android setup​

Build a development app​

Initialize the OVOK client​

Check the native configuration​