Skip to main content

Step 1: Create the React Native app

What we are building​

An Expo Router app that compiles for iOS and Android and contains the native dependencies needed for Ovok authentication, persistent client storage, and Bluetooth LE.

What you should already have​

  • Node.js installed.
  • Xcode for iOS, Android Studio for Android, or both.
  • A development device or simulator for building. Bluetooth pairing itself must be tested on a physical phone.

The current @ovok/native example uses Expo SDK 57, React Native 0.86.3, React 19.2.3, Android API 26 minimum, and iOS deployment target 16.4. Treat those as the repository example's compatibility baseline, not as a promise for every Expo combination. Match native package versions to the Expo SDK in your project; see the Native SDK installation guide.

The implementation​

Create an Expo Router tabs project and install the two Ovok packages:

npx create-expo-app@latest ovok-bp-rpm --template tabs
cd ovok-bp-rpm
npm install @ovok/core@^0.4.27 @ovok/native@^1.10.6 formik yup i18next react-i18next
npx expo install react-native-ble-plx react-native-permissions expo-secure-store expo-crypto expo-standard-web-crypto expo-dev-client expo-constants react-native-gesture-handler react-native-keyboard-controller react-native-paper react-native-safe-area-context react-native-svg @expo-google-fonts/dm-sans expo-build-properties

The minimum Ovok SDK versions validated for this tutorial are @ovok/core 0.4.27 and @ovok/native 1.10.6. Keep your lockfile and verify peer compatibility when upgrading. Expo installs should use npx expo install so native packages match your Expo SDK. The authentication forms also use Formik and Yup, while localization uses i18next and react-i18next.

Bootstrap the Ovok runtime before Expo Router​

Create index.js in the project root:

const { polyfillOvokWebAPIs } = require("@ovok/native/polyfills");

polyfillOvokWebAPIs();
require("expo-router/entry");

Set the app package's entry point to this file:

{
  "main": "index.js"
}

Keep this file in CommonJS form. The initializer must run before Expo Router imports screens or the client.

Configure the Bluetooth plugin​

Replace the generated app config with an app.config.ts based on this shape. Keep your real bundle identifiers from the Expo project:

import type { ExpoConfig } from "expo/config";

const config: ExpoConfig = {
  name: "Ovok BP RPM",
  slug: "ovok-bp-rpm",
  plugins: [
    "expo-router",
    [
      "@ovok/native",
      {
        bluetooth: {
          bluetoothAlwaysPermission:
            "Allow this app to connect to supported health devices.",
        },
      },
    ],
    ["react-native-permissions", { iosPermissions: ["Bluetooth"] }],
    [
      "expo-build-properties",
      {
        ios: { deploymentTarget: "16.4" },
        android: { minSdkVersion: 26 },
      },
    ],
    "expo-secure-store",
  ],
  ios: { bundleIdentifier: "com.example.ovokbprpm" },
  android: { package: "com.example.ovokbprpm" },
};

export default config;

The Ovok plugin configures the Bluetooth usage description and Android Bluetooth permissions for this foreground flow. The permissions plugin enables the iOS Bluetooth permission handler. Do not add background Bluetooth configuration: this tutorial only scans while the signed-in app is open. See the Bluetooth provider reference.

Add public sandbox configuration​

Create .env.example and keep a local .env or .env.local out of version control:

EXPO_PUBLIC_OVOK_BASE_URL=https://api.sandbox.ovok.com
EXPO_PUBLIC_TENANT_CODE=replace-with-your-sandbox-project-code

Expo embeds EXPO_PUBLIC_ values in the client bundle. Use them for public environment configuration only; never put passwords, private keys, or server credentials there. Step 2 will fill in the sandbox project's actual tenant code.

Build a native development app​

Expo Go does not contain the Bluetooth native module. Generate and compile a development build:

npx expo prebuild
npx expo run:ios
# or
npx expo run:android

Run Bluetooth testing on physical iOS and Android devices. Simulators can help compile and exercise non-Bluetooth screens, but they do not replace a real BLE scan, permission, pairing, or measurement test.

Important Ovok decisions​

  • The app opts into foreground Bluetooth only. Do not add HealthKit, Health Connect, social sign-in, notifications, or background service plugins for this tutorial.
  • The Bluetooth permission prompt needs a plain explanation that matches the app's actual use.
  • Email/password authentication does not need an OAuth redirect URL. A deep-link scheme is only needed if you later add a flow that returns the patient to the app through a link.

Expected result​

The Expo app compiles into a native development build on at least one target platform. Starting the app shows the template screen without a runtime error.

Common errors and troubleshooting​

  • Module not found for BLE: install react-native-ble-plx and react-native-permissions, then rebuild the native app.
  • Permission is missing after editing app config: rerun Prebuild and create a new development build. OTA JavaScript updates cannot add native permissions.
  • Expo Go opens instead of the development app: launch the custom development build produced by expo run.
  • iOS Bluetooth permission is blank: confirm the Ovok plugin's bluetoothAlwaysPermission text and the permissions plugin configuration, then rebuild.

Next step​

Continue to step 2: create and configure the Ovok project.