React Native

Use the Sonar iOS and Android SDKs through one React Native interface.

6 min read Updated Sep 14, 2026

Scope

React Native exposes one JavaScript-facing lifecycle while preserving the native permission and synchronization behavior of iOS (Swift) and Android (Kotlin).

The bindings do not conceal meaningful platform differences. Availability, permission prompts, background execution, and recovery guidance remain platform-specific where the operating systems behave differently.

Requirements

Area	Requirement
Project	Add the Sonar React Native package and install its native dependencies
Registration	Create separate Sonar application registrations for the iOS and Android builds
iOS	Configure HealthKit capabilities and privacy descriptions in the native project
Android	Configure Health Connect and Samsung Health in the native project
Identity	Provide an async client-token callback backed by your authenticated backend
Lifecycle	Forward app activation, sign-out, and user-switch events to the SDK

Install

bash

npm install @sonar/react-native-sdk@1.0.0
npx pod-install

The package autolinks its native modules. Expo applications must use a development build because Apple Health, Health Connect, and Samsung Health require native project configuration.

Initialize

typescript

import { Sonar } from "@sonar/react-native-sdk";

Sonar.configure({
  appId: "app_01K4M7D9R3W2V8Y6T5Q1N0PABC",
  environment: "sandbox",
});

await Sonar.authenticate({
  clientTokenProvider: async (context) => {
    const response = await customerApi.createSonarClientToken({
      appId: context.appId,
      installationId: context.installationId,
    });
    return response.client_token;
  },
});

const unsubscribe = Sonar.observeState((state) => {
  renderNativeHealthState(state);
});

await Sonar.connect("health_connect");

The token provider returns the client_token string from your backend response. Call unsubscribe() when the owning lifecycle ends. On iOS, connect apple_health; on Android, connect health_connect, samsung_health, or both.

Integration Flow

Install the Bindings

Add @sonar/react-native-sdk, install the iOS pods, and complete the native project configuration for every enabled provider.

Configure Each Native Project

Apple Health capabilities, Health Connect declarations, and Samsung Health registration remain native project configuration. Follow the corresponding iOS and Android reference before initializing JavaScript.

Configure and Authenticate

Configure the registered application and environment, then authenticate the native session through an async client-token provider backed by your backend. A Sonar API key must never be bundled with the app.

Connect a Provider

Call connect to request the Sonar-supported read set, record the provider connection, and start automatic synchronization. Handle the platform-specific authorization result returned by the active provider.

Observe and Synchronize

Subscribe to SDK state changes and remove listeners when the owning component or application session ends. Use sync() for an immediate incremental pull or resync(provider) for a safe full replay.

JavaScript Contract

Authentication binds one Sonar user to the current application installation and native SDK session.
Availability and permission results include platform- and provider-specific detail.
The complete Sonar-supported read set is mapped by each native SDK.
Synchronization exposes status, progress, retryable errors, and reauthorization state.
State subscriptions return a cleanup function that the app calls when the owning lifecycle ends.
Native storage restores the renewable session after app restart; hot reload does not create a second session.
Sign-out and user switching revoke the current session and clear its native credentials.

Framework Boundaries

Bare React Native and Expo development builds both require native project configuration.
Health-store capabilities, manifests, and package registration cannot be completed from JavaScript.
The customer owns native privacy declarations and store-review submissions.
The JavaScript package and native SDK versions must remain compatible.

Read Supported Native Data, the SDK Interface, SDK Synchronization, and Provider Lifecycle, or return to the Mobile SDK overview.