Android (Kotlin)

Read authorized data from Health Connect and Samsung Health and synchronize it with Sonar.

7 min read Updated Sep 14, 2026

Scope

The Android SDK coordinates availability and permissions for Health Connect and Samsung Health, reads authorized records incrementally, and uploads changes for the associated Sonar user.

Sonar treats them as distinct provider connections with separate source identities and data mappings. A user can connect or disconnect either provider independently. The SDK uploads every authorized source; Sonar’s server-side priority determines which overlapping workout or sleep record is preferred.

Both providers use the same Sonar session and synchronization lifecycle while preserving their platform-specific availability, permissions, and data-type behavior. Their current coverage is compared in Supported Native Data.

Provider Boundaries

Concern	Health Connect	Samsung Health
Platform surface	Android Health Connect APIs	Samsung Health Data SDK
Sonar connection	Independent provider	Independent provider
Data taxonomy	Health Connect record types	Samsung Health data types
Source priority	Separate workout and sleep configuration	Separate workout and sleep configuration
Distribution gate	Android and Google Play declarations	Samsung partnership and app registration

Requirements

Area	Requirement
Project	Add the Sonar Android SDK to the application module
Health Connect	Declare the requested record permissions and Play Console health-data access
Samsung Health	Complete Samsung partnership setup and register the package name and release signature
Identity	Provide a client-token callback backed by your authenticated backend
Background sync	Allow the SDK’s scheduled work and required network constraints

Install

Add the Sonar SDK from Maven Central:

kotlin

dependencies {
    implementation("co.sonarhealth:sonar-sdk:1.0.0")
}

Provider dependencies are included by the SDK. The application still owns its Health Connect declarations and Samsung Health partnership configuration.

Initialize

Initialize once from the Android application and authenticate after the customer signs in:

kotlin

import co.sonarhealth.sdk.Environment
import co.sonarhealth.sdk.NativeProvider
import co.sonarhealth.sdk.Sonar

Sonar.configure(
    context = applicationContext,
    appId = "app_01K4M7D9R3W2V8Y6T5Q1N0PABC",
    environment = Environment.SANDBOX,
)

Sonar.authenticate { context ->
    customerApi.createSonarClientToken(
        appId = context.appId,
        installationId = context.installationId,
    ).clientToken
}

val observation = Sonar.observeState { state ->
    renderNativeHealthState(state)
}

Sonar.connect(NativeProvider.HEALTH_CONNECT)

Authentication, provider, synchronization, and sign-out methods are suspending functions. configure and state observation are synchronous. Close the returned observation when its owner stops observing. Connect NativeProvider.SAMSUNG_HEALTH separately when the application offers both Android providers.

Integration Flow

Add the SDK

Add co.sonarhealth:sonar-sdk and enable every provider used by the registered application.

Configure the Selected Health Store

Configure Health Connect permissions and Play declarations separately from Samsung Health partnership registration, package-signature verification, and consent requirements.

Configure and Authenticate

Configure the SDK with the registered application and environment, then authenticate through the mobile app’s client-token provider. The SDK exchanges the short-lived token for a user-scoped session. A Sonar API key must never be included in the app.

Connect a Provider

Call connect to check the selected provider, request the complete Sonar-supported read set, record its independent connection, and start automatic synchronization. Handle unavailable, install-required, update-required, configuration-required, denied, partially granted, and connected states.

Observe and Synchronize

Observe SDK state for progress, retry, provider recovery, and reauthorization requirements. Use sync() for an immediate incremental pull or resync(provider) for a safe full replay.

Permission Behavior

The SDK checks Health Connect availability and provider updates across supported Android versions.
Samsung Health initialization verifies installation, SDK compatibility, partnership status, and the registered package signature.
The SDK maps the complete Sonar-supported read set to provider-specific record and data types.
Synchronization continues for granted types and reports missing or revoked permissions separately.
History and background-read permission are requested when the configured synchronization policy needs them.
Provider status includes the settings or installation recovery action the mobile app should present.

Synchronization Contract

The SDK owns Health Connect changes tokens and Samsung Health incremental cursors.
Duplicate uploads are idempotent; updated and deleted records update the normalized record.
Initial synchronization covers recent data first, then continues backwards for up to two years or as far as the provider permits.
Each provider remains a distinct connection when both are enabled for one user.
Sonar source priority determines which overlapping workout and sleep records are preferred.
Scheduled work batches pending changes and retries with backoff under Android execution constraints.
Sign-out or user switch revokes the current Sonar session and clears its local credentials before another user is initialized.

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