The Ultimate Guide to Reading Real-Time Samsung Health and Galaxy Watch Data in React Native

Building fitness, gym, and wellness applications in React Native is one of the fastest-growing niches in mobile healthtech. Whether you are tracking daily steps, analyzing sleep quality, or logging high-intensity resistance training, wearable telemetry is the lifeblood of the modern user experience.

Yet, if you have ever tried connecting a Samsung Galaxy Watch or Galaxy Fit 3 to a React Native app on Android, you know the frustration:

• Legacy community libraries are abandoned or fail on React Native 0.73+ and the New Architecture.
• Samsung's recent migration toward Health Connect and the new Samsung Health Data SDK left significant documentation gaps.
• Getting real-time live streaming (especially sub-3-second heart rate or skin temperature) was difficult due to wearable Bluetooth buffering delays.

To solve this once and for all, we created and published @groooh/react-native-samsung-health -- a production-ready, TypeScript-first React Native bridge built specifically for Samsung Health, Galaxy Watch 4/5/6/7/Ultra, and Galaxy Fit 3.

In this tutorial, you will learn how to configure your project, request permissions, stream real-time biometrics, read workouts with GPS breadcrumbs, and force Bluetooth sync on pull-to-refresh.

---

What Makes This Library Different?

Unlike basic wrappers that only fetch today's total steps, @groooh/react-native-samsung-health is built with a 3-Layer Real-Time Engine:

+--------------------------------------------------------+
|               GALAXY WATCH / GALAXY FIT 3              |
+---------------------------+----------------------------+
                            | BLE Broadcast
                            v
+--------------------------------------------------------+
|           SAMSUNG HEALTH (Local SQLite Store)          |
+---------------------------+----------------------------+
                            |
       +--------------------+--------------------+
       | Layer 1            | Layer 2            | Layer 3
       v                    v                    v
+--------------+    +--------------+    +-----------------+
|   Native     |    |  Background  |    |  Periodic BLE   |
|  Broadcast   |    |    Poller    |    |    Watchdog     |
|   Receiver   |    |  (Every 2s)  |    | (Force Sync 30s)|
+------++------+    +------++------+    +--------+--------+
       |                   |                     |
       +--------------------+---------------------+
                            |
                            v
             +---------------------------+
             |    React Native Bridge    |
             |   (Live Health Stream)    |
             +---------------------------+

1. Native BroadcastReceiver: Fires instantly when Samsung Health writes new watch sensor points to storage.
2. Configurable Background Poller: Continually fetches latest entries at an interval you specify (for example, 1000ms to 3000ms).
3. Periodic BLE Watchdog (triggerWatchSync): The Galaxy Fit 3 and Galaxy Watch buffer Bluetooth data to conserve battery. The library sends ACTION_FULL_SYNC_NEEDED every 30 seconds (or on user pull-to-refresh), forcing the band to dump its buffer immediately, ensuring sub-30s latency for real-time tracking.

---

Prerequisites

• React Native >= 0.73
• Android SDK minSdkVersion >= 29 (Android 10+)
• Kotlin >= 1.9
• Physical Android phone with Samsung Health installed (for production sensor data)

---

Step 1: Installation and Android Configuration

First, install the published package:

npm install @groooh/react-native-samsung-health

1. android/build.gradle

Ensure your minimum SDK is set to at least 29 (required by Samsung Health Data SDK):

buildscript {
    ext {
        minSdkVersion = 29
        compileSdkVersion = 35
        targetSdkVersion = 35
    }
}

2. android/settings.gradle

Link the native library module:

include ':react-native-samsung-health'
project(':react-native-samsung-health').projectDir = new File(rootProject.projectDir, '../node_modules/@groooh/react-native-samsung-health/android/app')

3. android/app/build.gradle

Enable kotlin-parcelize and add the project dependency:

apply plugin: "com.android.application"
apply plugin: "org.jetbrains.kotlin.android"
apply plugin: "com.facebook.react"
apply plugin: "kotlin-parcelize"

dependencies {
    implementation("com.facebook.react:react-android")
    implementation project(':react-native-samsung-health')
}

4. android/app/src/main/AndroidManifest.xml

Declare runtime permissions and Android 11+ <queries> so your app can discover Samsung Health:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
    <uses-permission android:name="android.permission.BODY_SENSORS" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

    <!-- Queries required on Android 11+ for Samsung Health package visibility -->
    <queries>
        <package android:name="com.sec.android.app.shealth" />
        <package android:name="com.samsung.android.wear.shealth" />
    </queries>

    <application ...>
        ...
    </application>
</manifest>

5. MainApplication.kt

Register SamsungHealthPackage() in your React Native package list:

import com.samsunghealthfit3.SamsungHealthPackage

class MainApplication : Application(), ReactApplication {
  override val reactHost: ReactHost by lazy {
    getDefaultReactHost(
      context = applicationContext,
      packageList = PackageList(this).packages.apply {
        add(SamsungHealthPackage())
      }
    )
  }
}

---

Enabling Developer Mode on Your Test Device

Samsung Health prevents third-party apps from accessing health data unless approved in Samsung's partner portal or running in Developer Mode. For development and testing:

1. Open Samsung Health on your phone.
2. Tap Settings and scroll down to About Samsung Health.
3. Tap the version number 10 times rapidly.
4. A toast message will pop up: "Developer mode is turned on".
5. Return to Settings. You will now see Developer mode. Toggle it ON.

---

Step-by-Step Code Recipes

1. Connection and Permission Handshake

Always call connect() before querying data. Then call requestPermissions(), which automatically launches the Samsung Health consent dialog:

import { connect, requestPermissions } from '@groooh/react-native-samsung-health';

async function initializeSamsungHealth() {
  try {
    const isConnected = await connect();
    if (!isConnected) {
      console.warn('Samsung Health is unavailable or not installed.');
      return false;
    }

    const grantedPermissions = await requestPermissions();
    console.log('Granted permissions:', grantedPermissions);
    return grantedPermissions.length > 0;
  } catch (error) {
    console.error('Initialization error:', error);
    return false;
  }
}

---

2. Real-Time Live Streaming (Heart Rate, Calories, SpO2, Skin Temp)

For live workout dashboards or resting vitals, subscribe to real-time updates:

import React, { useEffect, useState } from 'react';
import { View, Text, StyleSheet } from 'react-native';
import {
  startLiveTracking,
  stopLiveTracking,
  addHealthDataListener,
  LiveHealthData,
} from '@groooh/react-native-samsung-health';

export function LiveVitalsMonitor() {
  const [vitals, setVitals] = useState<LiveHealthData | null>(null);

  useEffect(() => {
    // 1. Listen for incoming stream updates
    const subscription = addHealthDataListener((data: LiveHealthData) => {
      setVitals(data);
    });

    // 2. Start the native background stream (poll interval: 2000ms)
    startLiveTracking({ intervalMs: 2000 });

    // 3. Clean up on unmount
    return () => {
      subscription.remove();
      stopLiveTracking();
    };
  }, []);

  return (
    <View style={styles.card}>
      <Text style={styles.title}>Live Galaxy Watch Vitals</Text>
      <Text style={styles.metric}>HR: {vitals?.heartRate ?? '--'} bpm</Text>
      <Text style={styles.metric}>Steps: {vitals?.steps ?? '--'}</Text>
      <Text style={styles.metric}>Active Kcal: {vitals?.calories ?? '--'} kcal</Text>
      <Text style={styles.metric}>Skin Temp: {vitals?.skinTemperature ?? '--'} deg C</Text>
      <Text style={styles.metric}>SpO2: {vitals?.bloodOxygen ?? '--'} %</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  card: { padding: 16, backgroundColor: '#ffffff', borderRadius: 12 },
  title: { fontSize: 16, fontWeight: '700', marginBottom: 12 },
  metric: { fontSize: 14, marginVertical: 4, color: '#334155' },
});

---

3. Detailed Sleep Stages (AWAKE, REM, LIGHT, DEEP)

Sleep quality is essential for athletic recovery. You can read the full sleep breakdown including duration, sleep score (0 to 100), and individual stage intervals:

import { readSleepDetail, SleepDetail, SleepStage } from '@groooh/react-native-samsung-health';

async function logSleepAnalysis() {
  const sleep: SleepDetail = await readSleepDetail();

  console.log(`Total Sleep: ${sleep.durationMinutes} mins`);
  console.log(`Sleep Score: ${sleep.sleepScore} / 100`);

  sleep.sessions.forEach(session => {
    session.stages.forEach((stage: SleepStage) => {
      console.log(`[${stage.stage}] ${new Date(stage.startTime).toLocaleTimeString()} -> ${new Date(stage.endTime).toLocaleTimeString()}`);
      // stage.stage is: 'AWAKE' | 'REM' | 'LIGHT' | 'DEEP'
    });
  });
}

---

4. Reading Workouts with GPS Routes and Telemetry Graphs

Need to display a workout graph or map? readExercises() fetches all exercise sessions with granular telemetry points and GPS breadcrumbs:

import { readExercises, Exercise } from '@groooh/react-native-samsung-health';

async function fetchRecentWorkouts() {
  const exercises: Exercise[] = await readExercises();

  exercises.forEach(w => {
    console.log(`Workout: ${w.type} (${w.durationMinutes} min, ${w.calories} kcal)`);
    console.log(`Avg HR: ${w.avgHeartRate} bpm | Max HR: ${w.maxHeartRate} bpm`);

    // Time-series telemetry points for pace and heart rate charting
    if (w.samples?.length) {
      console.log(`Telemetry samples: ${w.samples.length} points for graphs`);
    }

    // GPS route coordinates
    if (w.route?.length) {
      console.log(`GPS Track: ${w.route.length} lat/lng breadcrumbs`);
    }
  });
}

---

5. Instant Watch Sync on Pull-to-Refresh

When users pull down to refresh on their mobile screen, you want fresh watch telemetry immediately rather than waiting for Android's periodic sync:

import { triggerWatchSync, readAllData } from '@groooh/react-native-samsung-health';

async function handlePullToRefresh() {
  // 1. Force band to transmit fresh measurements over Bluetooth
  await triggerWatchSync();

  // 2. Read latest snapshot
  const freshSnapshot = await readAllData();
  console.log('Refreshed steps:', freshSnapshot.steps);
}

---

Complete API Quick-Reference

Method	Returns	Description
connect()	Promise<boolean>	Connects to the Samsung Health data store
requestPermissions()	Promise<string[]>	Triggers permission prompt; returns granted list
readAllData()	Promise<HealthData>	Daily snapshot (steps, calories, HR, SpO2, sleep, energy)
startLiveTracking(options)	Promise<boolean>	Starts real-time 3-tier streaming engine
stopLiveTracking()	Promise<boolean>	Halts real-time background stream
addHealthDataListener(fn)	HealthSubscription	Subscribes to live stream events
triggerWatchSync()	Promise<boolean>	Forces Galaxy Fit 3 / Watch to flush BLE buffer immediately
readSteps()	Promise<number>	Total steps taken today
readStepsTimeline()	Promise<StepBucket[]>	Hourly breakdown of steps taken today
readHeartRateHistory(hours)	Promise<HealthReading[]>	Continuous heart rate logs for the last N hours
readBloodOxygenHistory(hours)	Promise<HealthReading[]>	SpO2 readings over last N hours
readSkinTemperatureHistory(h)	Promise<HealthReading[]>	Wrist skin temperature readings over last N hours
readSleepDetail()	Promise<SleepDetail>	Sleep duration, score, and AWAKE/REM/LIGHT/DEEP stages
readBodyComposition()	Promise<BodyComposition>	Weight, body fat %, skeletal muscle, BMI, BMR, water
readExercises()	Promise<Exercise[]>	Workouts with GPS route and time-series graph telemetry
readEnergyScore()	Promise<EnergyScoreEntry[]>	Samsung Health AI Energy Score (0 to 100)
readFoodAndWater()	Promise<FoodAndWaterData>	Water intake (ml) and logged meals with macro totals
readDailyGoals()	Promise<DailyGoals>	Configured step, active calorie, and active time goals

---

Production Tips and Gotchas

1. Keep minSdkVersion at 29+: The Samsung Health Data SDK relies on Android 10+ APIs. Setting minSdkVersion 24 will cause Gradle manifest merger errors.
2. Clean Background Subscriptions: Always call subscription.remove() and stopLiveTracking() in your useEffect cleanup return to prevent battery drain.
3. Handle Missing Sensors Gracefully: Certain hardware lacks specific sensors (for example, Galaxy Fit 3 does not include BIA body composition; older watches lack continuous skin temperature). The library returns -1 or undefined rather than throwing errors, allowing you to display fallback UI.

---

Conclusion and Resources

Integrating Samsung Health and Galaxy wearables no longer requires digging through broken repositories or writing custom native Kotlin bindings. With @groooh/react-native-samsung-health, you get clean TypeScript types, 15+ granular query methods, and a high-performance 3-layer live streaming engine right out of the box.

• NPM Package: npmjs.com/package/@groooh/react-native-samsung-health
• License: MIT

---

Frequently Asked Questions (FAQ)

Does this library work on iOS?

No. @groooh/react-native-samsung-health is an Android-only native module because the Samsung Health Data SDK and Galaxy wearable Bluetooth communication protocols run natively within the Android operating system. For iOS applications, standard practice is to use Apple HealthKit (via libraries such as react-native-health).

Which Galaxy Watch and wearable models are supported?

The library supports all Samsung wearable devices paired with Samsung Health on Android 10+ (API 29+), including:

• Samsung Galaxy Watch series (Galaxy Watch 4, 5, 6, 7, and Watch Ultra running Wear OS)
• Samsung Galaxy Fit series (including Galaxy Fit 3 and Galaxy Fit 2)
• Samsung Galaxy Ring (for sleep, heart rate, skin temperature, and energy scores)
• Compatible third-party BLE accessories paired directly into Samsung Health

How does this library differ from Google Health Connect?

Google Health Connect is a system-level Android datastore acting as a synchronization bridge between multiple health apps. However, direct access to proprietary Galaxy wearable features -- such as continuous live streaming, the Samsung AI Energy Score, detailed BIA body composition (skeletal muscle, body water), and forced BLE band flushing (ACTION_FULL_SYNC_NEEDED) -- requires direct integration with the Samsung Health Data SDK. This library interfaces directly with Samsung Health to provide the lowest latency and deepest hardware metrics possible.

Do I need a Samsung Partner approval for production releases?

During development and internal testing, enabling Developer Mode on your Samsung test device (tapping the version number 10 times) allows full read and write access without partner approval. For public Google Play Store releases, Samsung requires developers to apply for partner approval via the Samsung Developer portal if accessing privileged health data types in production.

Why does Gradle fail with a minSdkVersion error during build?

The Samsung Health Data SDK requires Android 10 (API level 29) or higher. If your root android/build.gradle has minSdkVersion = 24 or lower, Gradle's manifest merger will fail. To resolve this, ensure minSdkVersion = 29 is configured under buildscript.ext in android/build.gradle.

Can I query data when the app is in the background?

Yes. You can invoke methods like readAllData() or readSteps() inside headless background tasks or background jobs (such as react-native-background-actions or WorkManager). However, active real-time streaming via startLiveTracking() should be restricted to foreground screens to preserve device battery life.

How does the library handle missing sensors on certain hardware?

If a user pairs a wearable that lacks a specific sensor (for instance, the Galaxy Fit 3 does not include a BIA body composition sensor, and older Galaxy watches do not have continuous skin temperature sensors), the library returns -1 or undefined rather than throwing fatal exceptions. This enables your React Native UI to display fallback or placeholder states cleanly.

What is the purpose of triggerWatchSync()?

Wearables like the Galaxy Fit 3 buffer collected biometric data in internal flash memory and transmit it over Bluetooth at intermittent intervals to save power. When a user opens your app or performs a pull-to-refresh, calling triggerWatchSync() sends an intent to the Galaxy Wearable plugin forcing the band to immediately dump its Bluetooth buffer into the local database, guaranteeing fresh metrics.