Skip to main content

​
Introduction

The Open Wearables React Native SDK (open-wearables-react-native-sdk) enables secure background synchronization of health data from Apple HealthKit (iOS), Samsung Health, and Health Connect (Android) to the Open Wearables platform. The SDK is built with the Expo Module API enabling install the app in Expo Project as well as in React Native CLI projects. On iOS, the React Native SDK is a wrapper around the native iOS SDK (open_wearables_ios_sdk). On Android, it wraps the native Android SDK (open_wearables_android_sdk). This means all the core sync logic — background execution, streaming uploads, secure storage, and retry mechanisms — is handled by the native implementations under the hood. The React Native layer provides a convenient TypeScript API for cross-platform apps.

React Native SDK Repository

View source code, report issues, and contribute to the React Native SDK.

Native iOS SDK

See the native iOS SDK documentation for the underlying iOS implementation.

Native Android SDK

See the native Android SDK documentation for the underlying Android implementation.

​
Features

  • Cross-Platform - Single TypeScript API for iOS (HealthKit) and Android (Samsung Health, Health Connect)
  • Background Sync - Health data syncs even when your app is in the background
  • Incremental Updates - Only syncs new data using anchored queries
  • Secure Storage - Credentials stored in iOS Keychain / Android EncryptedSharedPreferences
  • Dual Authentication - Token-based auth with auto-refresh or API key authentication
  • Resumable Sessions - Sync sessions survive app restarts
  • Wide Data Support - Steps, heart rate, workouts, sleep, and 40+ data types
  • Provider Selection - Choose between Samsung Health and Health Connect on Android

​
Requirements

RequirementDetails
iOS VersioniOS 15.0+
XcodeXcode 14+
Apple Developer AccountRequired for HealthKit entitlement
HealthKit CapabilityMust be enabled in Xcode
Physical DeviceHealthKit doesn’t work in iOS Simulator

​
Installation

1

Add the dependency

Currently, the SDK is only available locally. You can install it using the following command from the project root folder:
npm install
When we publish the package to npm (not available yet), you will use the following command:
npm install open-wearables
2

Run the app

Depending if you are using Expo or React Native CLI, follow the instructions below:

​
Using Expo

Expo projects using the Expo Modules API automatically link native dependencies. After installing the package, simply run your project.
npx expo run:ios
If your project does not yet contain native directories (ios/ and android/), Expo will automatically generate them.You can also generate them manually using:
npx expo prebuild

​
Using React Native CLI

For bare React Native projects, you must ensure that you have installed and configured the expo package before continuing. After installing the package, install the iOS CocoaPods dependencies:
npx pod-install
or manually:
cd ios && pod install
3

Config Plugin (optional)

You can customize the permission messages displayed to users by configuring the plugin in your app.json or app.config.js.
{
  "expo": {
    "plugins": [
      [
        "open-wearables",
        {
          "healthShareUsage": "Allow $(PRODUCT_NAME) to read your health data.",
          "healthUpdateUsage": "Allow $(PRODUCT_NAME) to write health data."
        }
      ]
    ]
  }
}

​
Quick Start

Here’s the minimal code to get health sync working: 

import OpenWearablesHealthSDK from "open-wearables";

// Configure the SDK with your backend host
OpenWearablesHealthSDK.configure("https://your-api-host.com");

// Sign in (token-based)
OpenWearablesHealthSDK.signIn(userId, accessToken, refreshToken, null);

// Or sign in (API key)
OpenWearablesHealthSDK.signIn(userId, null, null, apiKey);

// Request HealthKit authorization
await OpenWearablesHealthSDK.requestAuthorization(["steps", "heartRate", "sleep"]);

// Start background sync
await OpenWearablesHealthSDK.startBackgroundSync();

// Sync immediately
await OpenWearablesHealthSDK.syncNow();

​
Events

Subscribe to native SDK events using the standard Expo module event emitter: 

  const subscription = OpenWearablesHealthSDK.addListener("onLog", ({ message }) => {
    console.log("SDK log:", message);
  });

  const authSub = OpenWearablesHealthSDK.addListener(
    "onAuthError",
    ({ statusCode, message }) => {
      console.error(`Auth error ${statusCode}:`, message);
    }
  );

  // Clean up
  subscription.remove();
  authSub.remove();
EventPayloadDescription
onLog{ message: string }Log messages emitted by the native SDK
onAuthError{ statusCode: number, message: string }Authentication errors

​
Documentation

Integration Guide

Complete guide to integrating the SDK including authentication flow, backend setup, and best practices.

Troubleshooting

Common issues and their solutions for iOS and Android.

​
Supported Health Data Types

The SDK supports 40+ health data types across multiple categories:
TypeDescription
stepsStep count
distanceWalkingRunningWalking/running distance
distanceCyclingCycling distance
flightsClimbedFloors climbed
walkingSpeedAverage walking speed
walkingStepLengthStep length
walkingAsymmetryPercentageWalking asymmetry percentage
walkingDoubleSupportPercentageWalking double support percentage
sixMinuteWalkTestDistance6-minute walk test
activeEnergyActive energy burned
basalEnergyBasal (resting) energy burned
TypeDescription
heartRateHeart rate measurements
restingHeartRateResting heart rate
heartRateVariabilitySDNNHRV (SDNN)
vo2MaxVO2 max
oxygenSaturationBlood oxygen
respiratoryRateBreathing rate
TypeDescription
bodyMassWeight
heightHeight
bmiBody Mass Index
bodyFatPercentageBody fat %
leanBodyMassLean body mass
waistCircumferenceWaist circumference
bodyTemperatureBody temperature
TypeDescription
bloodGlucoseBlood glucose level
insulinDeliveryInsulin delivery
bloodPressureSystolicSystolic blood pressure
bloodPressureDiastolicDiastolic blood pressure
bloodPressureBlood pressure (correlation type)
TypeDescription
sleepSleep sessions and stages
mindfulSessionMeditation/mindfulness sessions
TypeDescription
menstrualFlowMenstrual flow
cervicalMucusQualityCervical mucus quality
ovulationTestResultOvulation test result
sexualActivitySexual activity
TypeDescription
dietaryEnergyConsumedCalories consumed
dietaryCarbohydratesCarbs
dietaryProteinProtein
dietaryFatTotalTotal fat
dietaryWaterWater intake
TypeDescription
workoutAll workout types with metadata
Not all data types are available on all providers. Samsung Health supports a subset of types compared to Health Connect and HealthKit. See the Android SDK docs for provider-specific availability.

​
Next Steps

Integration Guide

Complete step-by-step integration guide.

API Reference

Full API documentation on GitHub.