Installation and native setup

Compatibility baseline

The repository example currently uses:

• Expo SDK 57
• React Native 0.86.3
• React 19.2.3
• Android min SDK 26
• iOS deployment target 16.4 in the example app

These values describe the tested repository setup. Use npx expo install for Expo packages so the versions match the Expo SDK selected by your app. Do not copy the example app's app identifiers, Google IDs, Sentry IDs, or EAS project IDs.

Install the package

npm install @ovok/native

or:

yarn add @ovok/native

The package declares @ovok/core and the feature libraries as peer dependencies. Add only the groups your app uses:

Feature	Packages to install
Core UI	@ovok/core, react, react-native, react-native-paper, react-native-svg, @gorhom/bottom-sheet, react-native-gesture-handler, react-native-reanimated, react-native-safe-area-context
Auth	@react-native-google-signin/google-signin, expo-apple-authentication, expo-web-browser, formik, yup, i18next, react-i18next
Bluetooth	react-native-ble-plx, react-native-permissions
HealthKit	@kingstinct/react-native-healthkit
Health Connect	expo-health-connect, react-native-health-connect
Network-aware import	@react-native-community/netinfo
PDFs and files	react-native-pdf, react-native-blob-util
Optional background notifications	expo-notifications
Optional background persistence	Any durable store implementing getItem and setItem

The exact peer dependency names and ranges are always defined in the root package.json; the table above is a feature map, not a second package manifest.

Native build requirement

The SDK cannot run its native features in stock Expo Go. After installing native dependencies or changing an Expo config plugin, rebuild the development client:

npx expo prebuild
npx expo run:ios
npx expo run:android

Use npx expo prebuild --clean only when you intentionally want Expo to regenerate native projects. Review generated native diffs before committing them.

Config plugins and permissions

The example app uses these relevant plugins:

plugins: [
  "expo-apple-authentication",
  [
    "@react-native-google-signin/google-signin",
    { iosUrlScheme: "com.googleusercontent.apps.<your-client-id>" },
  ],
  [
    "react-native-ble-plx",
    {
      isBackgroundEnabled: true,
      modes: ["peripheral", "central"],
      bluetoothAlwaysPermission:
        "Allow $(PRODUCT_NAME) to connect to Bluetooth devices",
    },
  ],
  [
    "react-native-permissions",
    { iosPermissions: ["Bluetooth", "Notifications"] },
  ],
  [
    "@kingstinct/react-native-healthkit",
    {
      NSHealthShareUsageDescription: "Explain why the app reads HealthKit data.",
      NSHealthUpdateUsageDescription: "Explain why the app writes HealthKit data.",
      background: true,
    },
  ],
  "expo-health-connect",
]

Add only the plugins used by the app, and use the current setup instructions for each native dependency. Config plugins are applied at build time; changing the JavaScript configuration after a binary has been built does not change that binary.

iOS

For BLE, configure the Bluetooth usage descriptions. For HealthKit, enable the HealthKit capability and include the read/write usage descriptions. The HealthKit background option is required when using AppleHealthSync with backgroundDelivery.

Apple Sign-In is iOS-only and requires usesAppleSignIn plus the Apple developer capability. Test BLE, HealthKit, restoration, and social login on physical hardware.

Android

The example declares the Bluetooth permissions, foreground-service permissions, and Health Connect read/write permissions it actually uses:

{
  "android": {
    "permissions": [
      "android.permission.BLUETOOTH_CONNECT",
      "android.permission.BLUETOOTH_SCAN",
      "android.permission.FOREGROUND_SERVICE",
      "android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE",
      "android.permission.FOREGROUND_SERVICE_DATA_SYNC",
      "android.permission.POST_NOTIFICATIONS",
      "android.permission.health.READ_HEALTH_DATA_IN_BACKGROUND"
    ]
  }
}

Declare the individual android.permission.health.READ_* and WRITE_* records that match your dataToSync configuration. Android 13+ notification permission is needed when the app requests background measurement notifications.

Polyfill initialization

Call polyfillMedplumWebAPIs once from the app entry point before creating or using the Ovok client:

import { polyfillMedplumWebAPIs } from "@ovok/native";

polyfillMedplumWebAPIs();

The function is re-exported from @medplum/expo-polyfills. Do not call it on every render.

Build verification

After setup, verify the actual native project rather than only TypeScript:

npx expo config --type public
npx expo prebuild
npx expo run:ios
npx expo run:android

Then exercise at least one auth flow, one foreground BLE reading, and one health authorization flow on each platform you ship.