The Mobile SDK reads health data directly from on-device health stores — Apple Health, Health Connect, and Samsung Health — and sends it to the Sonar platform. Once synced, data enters the same normalization and scoring pipeline as Cloud API data, and you query it through the same REST API regardless of source.

The SDK is a data collection pipe, not a query library. It handles permissions, background syncing, and upload. Your backend receives processed data through the Events API and Webhooks, and queries it via the REST API.

Architecture

Your Mobile AppOn-DeviceHealth StoreSonar PlatformYour BackendSonar SDKIngestionNormalizedDataREST API readsyncquery Your Mobile AppOn-DeviceHealth StoreSonar PlatformYour BackendSonar SDKIngestionNormalizedDataREST API readsyncquery

Your Job vs. the SDK's Job

Step You handle SDK handles
Auth token Generate a mobile token from your backend Consume token during initialization
OS permissions Trigger connection at the right UX moment Present the system permission dialog, handle results
Data sync Nothing — it happens automatically Read health store, batch data, send to Sonar
Background sync Configure capabilities/manifest once Schedule and execute syncs, queue offline data
Data access Query REST API for metrics and scores N/A — data is accessed server-side, not through the SDK

Supported Platforms

iOS (Swift) Android (Kotlin) React Native
Health stores Apple Health Health Connect, Samsung Health All three (via native bridges)
Package SonarSDK (Swift Package) co.sonar:sonar-android (Maven) @sonar-health/react-native-apple-health + @sonar-health/react-native-android
Min version iOS 14+ API 28+ RN 0.71+, iOS 14+ / API 28+
Language Swift Kotlin TypeScript
Background sync HealthKit background delivery WorkManager Native mechanisms via bridge
Expo — — Config plugins for managed workflow

Which SDK Should I Use?

Your situation Recommendation
Native iOS app (Swift/SwiftUI) iOS SDK
Native Android app (Kotlin/Compose) Android SDK
React Native, both platforms Both React Native packages with platform detection
React Native, iOS only @sonar-health/react-native-apple-health
React Native, Android only @sonar-health/react-native-android
Flutter or other cross-platform Use native SDKs via platform channels
Web-only product, no mobile app Skip the SDK — use Cloud API instead

Authentication Flow

Every SDK connection requires a single-use mobile token generated by your backend. This keeps your API credentials off the device.

Your BackendSonar APIYour AppSDKSonar Backend POST /auth/mobile-token(API key + user_id)token (5 min, single-use)pass token to clientinitialize(token)exchange tokenfor session Your BackendSonar APIYour AppSDKSonar Backend POST /auth/mobile-token(API key + user_id)token (5 min, single-use)pass token to clientinitialize(token)exchange tokenfor session

Generating a Mobile Token

Your backend calls the Sonar API to create a token, then passes it to the mobile client:

POST /v1/auth/mobile-token

Generates a single-use token for SDK initialization. Expires in 5 minutes.

Parameter Type Required Description
user_id string yes The Sonar user ID (e.g., usr_abc123)
scopes string[] no Metric categories to request (default: all)
python 
import requests

BASE = "https://api.sonarhealth.co/v1"

resp = requests.post(
    f"{BASE}/auth/mobile-token",
    headers={"Authorization": "Bearer sk_live_abc123"},
    json={"user_id": "usr_abc123"},
)
token = resp.json()["token"]  # Pass this to the mobile SDK
typescript 
const BASE = "https://api.sonarhealth.co/v1";

const resp = await fetch(`${BASE}/auth/mobile-token`, {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_live_abc123",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ user_id: "usr_abc123" }),
});
const { token } = await resp.json(); // Pass this to the mobile SDK

Available Data

The SDK collects data from the on-device health store and uploads it to Sonar. Each store has different metric coverage — Apple Health is the broadest, Health Connect and Samsung Health cover the core set.

Category Apple Health Health Connect Samsung Health
Activity Steps, distance, exercise, flights, stand time, mindfulness Steps, distance, exercise, mindfulness, VO2 max Steps, distance, exercise
Sleep Full stages, efficiency, overnight vitals (HR, HRV, SpO2, temp) Duration, stages Duration, stages
Vitals HR, RHR, HRV (RMSSD + SDNN), respiratory rate, SpO2, blood glucose, blood pressure HR, RHR, HRV (RMSSD), respiratory rate, VO2 max HR, RHR, HRV (RMSSD)
Body Weight, height, BMI, body fat, lean mass Weight, height, BMI, body fat, lean mass Weight, height, BMI, body fat
Energy Active calories, resting energy, total calories Active calories, resting energy, total calories Active calories, total calories
Nutrition Full macros, water, fiber, sodium Calories consumed Calories consumed
Workouts 80+ activity types with HR zones, distance, calories 80+ activity types with HR zones, distance, calories Activity types with duration, calories

See Data Catalog for the full metric-by-metric reference with metric_id values and per-provider availability.

What Happens After Sync

When the SDK syncs, Sonar normalizes the data, applies multi-device deduplication, and makes it available via the REST API. Events fire (data.updated, score.updated) so your backend knows exactly when new data is ready.

Typical latency from device sync to API availability is seconds to minutes. Use webhooks or the Events API to know exactly when new data is ready.

Go Deeper