Skip to main content

Installation & Setup

This guide covers the complete installation process for the Ovok Mobile SDK, including all required dependencies and platform-specific configurations.

Installation​

1. Install the SDK​

Install the Ovok Mobile SDK in your React Native project:

npm install @ovok/native

2. Install Dependencies​

The Ovok Mobile SDK requires additional packages to function properly. Install all mandatory peer dependencies:

npx expo install react-native-keyboard-controller @react-native-google-signin/google-signin expo-apple-authentication @kingstinct/react-native-healthkit@^8.5.0 @react-native-community/netinfo expo-health-connect react-native-blob-util react-native-pdf react-native-permissions react-native-svg react-native-health-connect expo-build-properties

Required Dependencies:

  • @kingstinct/react-native-healthkit@^8.5.0 - iOS HealthKit integration
  • @react-native-community/netinfo - Network connectivity detection
  • @react-native-google-signin/google-signin - Google authentication
  • expo-apple-authentication - Apple Sign-In (iOS only)
  • expo-health-connect - Android Health Connect integration
  • react-native-blob-util - File handling and blob operations
  • react-native-pdf - PDF document support
  • react-native-permissions - Permission management
  • react-native-keyboard-controller - Enhanced keyboard handling
  • react-native-svg - Render icons
  • react-native-health-connect - Android Health Connect integration
  • expo-build-properties - Build properties for Android and iOS

Configuration​

Google Sign-In Configuration​

The SDK includes Google Sign-In functionality through @react-native-google-signin/google-signin. Add the config plugin to your app.json or app.config.js:

{
  "expo": {
    "plugins": [
      [
        "@react-native-google-signin/google-signin",
        {
          "iosUrlScheme": "com.googleusercontent.apps._your_id_here_"
        }
      ]
    ]
  }
}

For detailed configuration instructions, refer to the React Native Google Sign-In Expo setup guide.

Apple Authentication Configuration​

The SDK includes Sign-in with Apple functionality through expo-apple-authentication. Add the config plugin to your app.json or app.config.js:

{
  "expo": {
    "plugins": ["expo-apple-authentication"],
    "ios": {
      "usesAppleSignIn": true
    }
  }
}

Important Notes:

  • Apple Authentication is iOS only and does not support Android or web
  • Any app with third-party authentication options must provide Apple authentication to comply with App Store Review guidelines
  • Limited testing is available on iOS Simulator; use a real device for comprehensive testing

For detailed configuration instructions, refer to the Expo Apple Authentication documentation.

HealthKit Configuration​

The SDK includes HealthKit functionality through @kingstinct/react-native-healthkit for iOS health data integration. Add the config plugin to your app.json or app.config.js:

{
  "expo": {
    "plugins": [
      [
        "@kingstinct/react-native-healthkit",
        {
          "NSHealthShareUsageDescription": "This app reads health data to provide personalized healthcare insights",
          "NSHealthUpdateUsageDescription": "This app writes health data to track your wellness progress",
          "background": true
        }
      ]
    ]
  }
}

Important Notes:

  • HealthKit is iOS only and requires physical device testing
  • You must request authorization before accessing health data to prevent app crashes
  • HealthKit capability must be enabled in your Apple Developer account

For detailed usage and API documentation, refer to the React Native HealthKit documentation.

Network Information Configuration​

The SDK includes network connectivity detection through @react-native-community/netinfo. No additional configuration is required - the library works out of the box after installation.

Features:

  • Real-time network connectivity monitoring
  • Connection type detection (WiFi, Cellular, etc.)
  • Network quality assessment
  • Cross-platform support (iOS and Android)

For detailed usage instructions, refer to the Expo NetInfo documentation.

Health Connect Configuration​

The SDK includes Android Health Connect functionality through expo-health-connect for Android health data integration. Add the config plugin to your app.json or app.config.js:

{
  "expo": {
    "plugins": ["expo-health-connect"]
  },
  "plugins": [
    [
      "expo-build-properties",
      {
        "android": {
          "compileSdkVersion": 35,
          "targetSdkVersion": 35,
          "minSdkVersion": 26
        }
      }
    ]
  ]
}

Important Notes:

  • Health Connect is Android only and complements HealthKit on iOS
  • Requires Android API level 26 (Android 8.0) or higher
  • Users must have Health Connect app installed on their device

Permissions Configuration​

The SDK uses react-native-permissions for managing various device permissions. Add the config plugin with required iOS permissions:

{
  "expo": {
    "plugins": [
      [
        "react-native-permissions",
        {
          "iosPermissions": ["Bluetooth", "Notifications"]
        }
      ]
    ]
  }
}

Keyboard Controller Setup​

The SDK uses react-native-keyboard-controller for enhanced keyboard handling. Follow these steps:

  1. Android: No additional setup required after installation.

  2. iOS: The library should work automatically after running pod install.

  3. Optional Configuration: For advanced keyboard behavior, mount KeyboardProvider outside the SDK's OvokProvider in your app's root component. The full canonical chain is documented in Basic Setup below — this snippet just shows the keyboard-aware-only minimum:

import { KeyboardProvider } from "react-native-keyboard-controller";
import { OvokProvider, OvokClient } from "@ovok/core";
import { ExpoClientStorage } from "@ovok/native";

const ovokClient = new OvokClient({
  storage: new ExpoClientStorage(),
  baseUrl: "https://api.ovok.com",
  fhirUrlPath: "/fhir",
  tenantCode: "your-tenant-code",
});

export default function App() {
  return (
    <KeyboardProvider>
      <OvokProvider client={ovokClient}>{/* Your app content */}</OvokProvider>
    </KeyboardProvider>
  );
}

Do NOT use import { Provider } from "@ovok/mobile" — @ovok/mobile is a legacy package name that does not resolve on npm. The SDK ships as @ovok/native, and there is no bare Provider export. Use OvokProvider from @ovok/core for the FHIR/auth client, and ThemeProvider as OvokThemeProvider from @ovok/native for the UI theme — both shown in the Basic Setup below.

Complete Configuration Example​

Here's a complete app.json configuration with all SDK plugins and platform-specific settings:

{
  "expo": {
    "plugins": [
      "expo-apple-authentication",
      [
        "@react-native-google-signin/google-signin",
        {
          "iosUrlScheme": "com.googleusercontent.apps._your_id_here_"
        }
      ],
      [
        "react-native-permissions",
        {
          "iosPermissions": ["Bluetooth", "Notifications"]
        }
      ],
      [
        "@kingstinct/react-native-healthkit",
        {
          "NSHealthShareUsageDescription": "We need access to your health data to provide personalized healthcare insights",
          "NSHealthUpdateUsageDescription": "We need access to update your health data for tracking your wellness progress",
          "background": true
        }
      ],
      "expo-health-connect",
      [
        "expo-build-properties",
        {
          "android": {
            "compileSdkVersion": 35,
            "targetSdkVersion": 35,
            "minSdkVersion": 26
          }
        }
      ]
    ],
    "ios": {
      "usesAppleSignIn": true,
      "infoPlist": {
        "NSBluetoothPeripheralUsageDescription": "Allow $(PRODUCT_NAME) to connect to Bluetooth devices",
        "NSLocationWhenInUseUsageDescription": "Allow $(PRODUCT_NAME) to access your location",
        "NSBluetoothAlwaysUsageDescription": "Allow $(PRODUCT_NAME) to connect to Bluetooth devices",
        "NSPhotoLibraryUsageDescription": "Allow $(PRODUCT_NAME) to access your photo library"
      }
    },
    "android": {
      "permissions": [
        "android.permission.BLUETOOTH",
        "android.permission.BLUETOOTH_ADMIN",
        "android.permission.BLUETOOTH_CONNECT",
        // Add the required react-native-health-connect permissions
        "android.permission.health.READ_BODY_TEMPERATURE"
      ]
    }
  }
}

Key Configuration Notes:

  • Replace _your_id_here_ with your actual Google OAuth client ID
  • iOS permissions are configured in infoPlist for Bluetooth, location, and photo library access
  • Android permissions include comprehensive Health Connect read/write permissions
  • HealthKit background processing is enabled for continuous health monitoring

Final Steps​

After adding all config plugins, rebuild your app:

npx expo prebuild --clean
npx expo run:android && npx expo run:ios

Basic Setup​

Once installation is complete, configure your app with the complete provider setup in your root layout file. Create or update app/_layout.tsx with the following configuration that includes client setup, theme configuration, and all necessary providers:

// app/_layout.tsx
import { OvokClient, OvokProvider } from "@ovok/core";
import {
  BottomSheetModalProvider as BSMPVOVK,
  DEFAULT_COLORS,
  DEFAULT_MULTIPLIERS,
  ExpoClientStorage,
  ThemeProvider as OvokThemeProvider,
  polyfillMedplumWebAPIs,
} from "@ovok/native";
import { BottomSheetModalProvider } from "@gorhom/bottom-sheet";
import { DarkTheme, ThemeProvider } from "@react-navigation/native";
import { Stack } from "expo-router";
import { KeyboardProvider } from "react-native-keyboard-controller";

// Initialize required polyfills for medical APIs
polyfillMedplumWebAPIs();

// Configure client storage
const storage = new ExpoClientStorage();

// Initialize Ovok client with your configuration
const ovokClient = new OvokClient({
  storage,
  cacheTime: 0,
  baseUrl: "https://api.ovok.com",
  fhirUrlPath: "/fhir",
  socialLoginClientId: "1000.000000000000000000000000000000000000",
  tenantCode: "ovok", // replace it with yours
});

export default function RootLayout() {
  return (
    <KeyboardProvider>
      <OvokProvider client={ovokClient}>
        <OvokThemeProvider
          theme={{
            colors: DEFAULT_COLORS,
            dark: true,
            spacingMultiplier: DEFAULT_MULTIPLIERS.spacing,
            borderRadiusMultiplier: DEFAULT_MULTIPLIERS.borderRadius,
          }}
        >
          <BottomSheetModalProvider>
            <BSMPVOVK>
              <ThemeProvider value={DarkTheme}>
                <Stack />
              </ThemeProvider>
            </BSMPVOVK>
          </BottomSheetModalProvider>
        </OvokThemeProvider>
      </OvokProvider>
    </KeyboardProvider>
  );
}

Configuration Options​

OvokClient Configuration:

  • storage - Client storage implementation using ExpoClientStorage
  • cacheTime - Cache duration in milliseconds (0 for no caching)
  • baseUrl - Your API base URL
  • fhirUrlPath - FHIR endpoint path
  • socialLoginClientId - Your social login client identifier
  • tenantCode - Your tenant/organization code

Theme Configuration:

  • colors - Color scheme using DEFAULT_COLORS or custom colors
  • dark - Enable dark mode theme
  • spacingMultiplier - Spacing scale multiplier for consistent layouts
  • borderRadiusMultiplier - Border radius scale multiplier

Provider Hierarchy:

  1. KeyboardProvider - Enhanced keyboard handling
  2. OvokProvider - Core SDK client and state management
  3. OvokThemeProvider - Theme and styling system
  4. BottomSheetModalProvider - Modal sheet functionality
  5. BSMPVOVK - Required for SDK component sheets
  6. ThemeProvider - React Navigation theming

Common Errors​

These three errors account for ~90% of "the SDK isn't working" reports. Each has the same root cause: wrong import name or missing config-plugin entry. Fix them once and they don't recur.

"Element type is invalid: expected a string ... but got: undefined"​

A named import resolved to undefined and JSX rendered <undefined>. The two most common offenders, both with one-line fixes:

You wroteRealityFix
import { OvokThemeProvider } from "@ovok/native"The export is ThemeProvider. There is no bare OvokThemeProvider.import { ThemeProvider as OvokThemeProvider } from "@ovok/native"
import { OvokProvider } from "@ovok/native"OvokProvider lives in @ovok/core.import { OvokProvider, OvokClient } from "@ovok/core"
import { ExpoClientStorage } from "@ovok/core"Re-exported by @ovok/native (originally from @medplum/expo-polyfills).import { ExpoClientStorage } from "@ovok/native"
import { Provider } from "@ovok/mobile"@ovok/mobile is a legacy package name that doesn't resolve on npm. There is no bare Provider.See Basic Setup for the canonical chain — typically OvokProvider + OvokThemeProvider.

"No permission handler detected for type ..."​

react-native-permissions is installed in package.json but its Expo config plugin entry is missing from app.json. Without the plugin entry, iOS does NOT link the PermissionHandler subspecs in the Podfile, so check() / request() calls crash even though the JS package is on disk.

Add the plugin entry shown in Permissions above:

{
  "expo": {
    "plugins": [
      ["react-native-permissions", { "iosPermissions": ["Bluetooth", "Notifications"] }]
    ]
  }
}

Run npx expo prebuild --clean (or rebuild your dev client) after the change so the Podfile picks up the subspecs.

"TurboModuleRegistry.getEnforcing(...): 'X' could not be found"​

The JS package is installed but the native module is NOT in the dev client binary. Either:

  • You're running the SDK against a stock Expo Go build — Expo Go ships a fixed native-module set and does NOT include @ovok/native's peers. Build a development client (npx expo run:ios / expo run:android) or use a prebuilt one (e.g. the Ovok Builder Companion).
  • Your dev client was built before you added the native module. Rebuild with npx expo prebuild --clean && npx expo run:ios so the Podfile / MainApplication pick it up.
  • The package's Expo config plugin entry is missing from app.json. See Complete Configuration Example for the full set.

Next Steps​

With installation complete, you're ready to start using the SDK components: