Ovok Mobile SDK

A React Native SDK for integrating Ovok Core healthcare services into native Expo and React Native applications. It combines app-facing healthcare UI with Bluetooth device integration, HealthKit/Health Connect import, and background delivery primitives.

✨ Features

• 🔐 Authentication - Sign-in, registration, password reset, profile, and account controls
• 🩺 Bluetooth - BLE discovery, device protocols, measurements, and device UI
• ❤️ Health data - Apple HealthKit and Android Health Connect authorization and import
• 🔄 Background work - Durable BLE result delivery and Android Health Connect scheduling
• 📱 Healthcare UI - Patients, observations, measurements, content, diary, journal, tiles, and questionnaires
• 🎨 Theming - Material 3 theme tokens, spacing, and radius multipliers
• 🌍 Localization - Language switching and localized device catalog labels
• 📖 TypeScript - Public root and subpath exports with generated declarations

🚀 Quick start

Installation

npm install @ovok/native @ovok/core
# or
yarn add @ovok/native @ovok/core

The SDK uses native modules. Expo Go is not sufficient; add the required config plugins, build a development client, and follow the installation and native setup guide. Install @ovok/core alongside the native package. The root @ovok/native import exposes the shared UI, authentication, theme, and Bluetooth-management surface. Optional native integrations such as health import, PDF viewing, background services, and themeable UI flows are available through documented subpaths. Install the peer packages listed in the installation matrix for the entry points you use. Apps integrating one feature or device can use a subpath export and install only that import graph. Use npx expo install for Expo native dependencies so their versions match the app's Expo SDK.

📚 Documentation

Read the complete SDK guide for:

• installation and provider setup;
• authentication and app-shell composition;
• Bluetooth, supported devices, images, credits, and localization;
• iOS/Android background sync;
• HealthKit and Health Connect import;
• reusable Bluetooth/health hooks, stable result IDs, background-safe storage, and the opt-in Expo config plugin;
• the public API map, troubleshooting, and release checks.

Android battery exemption prompt

requestBatteryOptimizationExemption is an explicit opt-in. The SDK only opens Android's battery-exemption screen while an Activity is in the foreground. If a background scan enables the service, the request is kept pending and retried when the app next returns to the foreground. Keep this option disabled while the app is launching another system permission prompt, such as Android 13 notification permission; enable it after that prompt has completed.

Patient registration invitations

When a project enables clinician invitations for business email addresses, the register form can return nextStep: "clinician-invite". The form does not save a session or call onSuccess for this response; use onNextStep to show a check-your-email state. If the person intended to register as a patient, the invitation email includes a continueAsPatientToken link. Read that query parameter in the host app's route and pass it to Register.EmailForm; the SDK does not install a deep-link listener.

const params = useLocalSearchParams<{
  continueAsPatientToken?: string | string[];
}>();
const continueAsPatientToken = Array.isArray(params.continueAsPatientToken)
  ? params.continueAsPatientToken[0]
  : params.continueAsPatientToken;

<Register.EmailForm
  tenantCode={tenantCode}
  continueAsPatientToken={continueAsPatientToken}
  onNextStep={() => setCheckEmail(true)}
  onSuccess={handleAuthenticated}
>
  <Register.EmailForm.Inputs />
  <Register.EmailForm.RegisterButton />
</Register.EmailForm>;

Set the project's PATIENT_SIGNUP_URL to the HTTPS URL for this route. Configure iOS associatedDomains (for example, applinks:signup.example.com) and Android intentFilters for the same host/path in the app config. The host also needs a valid Apple apple-app-site-association file and Android assetlinks.json; make sure the invitation URL uses that verified host and reaches the route with its query parameter intact. A missing, invalid, or expired token is returned as an HTTP 400 and displayed as the form's submit error.

CMS content

useCmsDocument, useCmsDocuments, useLegalPage, and useReleaseNotes are the @ovok/core hooks of the same names. They read in the app's i18next language (useCmsLocale()) unless options.locale is set, and read again when i18n.changeLanguage selects a different CMS locale. A language the CMS does not carry, and cimode, read en. Signed out, only useLegalPage(slug, { tenantCode }) and useCmsTranslations({ tenantCode }) read (another hook reads only with allowSignedOut: true and a tenantCode); the others return a SignInRequiredError as their error without sending a request. The @ovok/core README describes the auth modes. These hooks need the Ovok Core backend release that serves /v1/public/cms, so deploy the backend before releasing this SDK version.

Translations

Call useCmsTranslations({ tenantCode }) once, near the root of the app. It reads the CMS translations collection in the i18next language and adds its texts to i18next's translation namespace under the CMS locale (de, which a de-DE language still resolves through). The app's own strings win over the CMS, and the CMS wins over the SDK's built-in English; a refreshed CMS text replaces the one it wrote before. When a text changes, components re-render through i18next's languageChanged event; the language itself is not changed.

📄 License

See LICENSE and the package metadata for the applicable license terms. The repository currently requires those two sources to be reconciled before making a new licensing claim.