Android Health Connect Integration Guide

Overview

This guide walks you through the complete integration of the Open Wearables Android SDK into a native Kotlin application, from backend setup to production deployment.

Set up backend authentication endpoint

Initialize and configure the SDK

Implement sign-in flow

Select health provider

Request health permissions

Start background sync

Read the Mobile SDK Integration Guide first. It covers what is the same on every platform: authentication, the backend token endpoint, the SDK lifecycle, and the production checklist. This page shows the Kotlin code for each step.

Step 1: Backend Setup

Your backend exchanges your app credentials for user-scoped SDK tokens and forwards them to the app - the app never sees app_id / app_secret. See Backend Endpoint for the setup and example code.

Step 2: SDK Initialization & Configuration

Initialize the SDK once in your Application class or main activity, then configure it with your backend host.

import com.openwearables.health.sdk.OpenWearablesHealthSDK

class MyApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        // Initialize SDK (once per app lifecycle)
        val sdk = OpenWearablesHealthSDK.initialize(this)

        // Optional: Set up logging
        sdk.logListener = { message ->
            Log.d("HealthSDK", message)
        }

        // Optional: Set log level (default is OWLogLevel.DEBUG — logs only in debuggable builds)
        sdk.logLevel = OWLogLevel.ALWAYS

        // Optional: Handle auth errors (e.g. token expired)
        sdk.authErrorListener = { statusCode, message ->
            Log.e("HealthSDK", "Auth error $statusCode: $message")
        }

        // Configure with your backend host
        sdk.configure(host = "https://api.openwearables.io")
    }
}

Configuration Options

Parameter	Type	Description
`host`	`String`	Required. The Open Wearables API base URL (host only, without path suffix)

Provide only the base host URL, e.g. https://your-domain.com. Do not append /api/v1/ or any other path — the SDK adds the required path prefix automatically.

// For self-hosted Open Wearables
sdk.configure(host = "https://your-domain.com")

Session Restoration

The SDK automatically restores credentials from EncryptedSharedPreferences:

val sdk = OpenWearablesHealthSDK.getInstance()

if (sdk.isSessionValid()) {
    val userId = sdk.restoreSession()
    Log.d("HealthSDK", "Session restored for user: $userId")
} else {
    // Need to sign in
}

After getting credentials from your backend, sign in with the SDK.

The userId parameter is the Open Wearables User ID (UUID) — the id returned by the Create User endpoint. Do not pass your own external_user_id here.

Token-Based Authentication (Recommended)

suspend fun connectHealth(credentials: HealthCredentials) {
    val sdk = OpenWearablesHealthSDK.getInstance()

    sdk.signIn(
        userId = credentials.userId,
        accessToken = credentials.accessToken,
        refreshToken = credentials.refreshToken,
        apiKey = null
    )

    Log.d("HealthSDK", "Signed in: ${credentials.userId}")
}

API Key Authentication

For simpler setups (e.g. internal tools):

sdk.signIn(
    userId = "user123",
    accessToken = null,
    refreshToken = null,
    apiKey = "your_api_key"
)

API key authentication embeds the key in the app. Only use this for internal or trusted applications. For production apps, always use token-based authentication.

Automatic Token Refresh

When you provide a refreshToken, the SDK automatically handles 401 responses by refreshing the access token and retrying the request. You can also update tokens manually:

sdk.updateTokens(
    accessToken = newAccessToken,
    refreshToken = newRefreshToken
)

Step 4: Select Health Provider

Before requesting permissions, you must select a health data provider:

val sdk = OpenWearablesHealthSDK.getInstance()

// Check available providers
val providers = sdk.getAvailableProviders()
for (p in providers) {
    Log.d("HealthSDK", "${p["displayName"]} (${p["id"]}) - available: ${p["isAvailable"]}")
}

// Set the provider based on user selection or your default
val success = sdk.setProvider("google") // or "samsung" for Samsung Health
if (!success) {
    Log.e("HealthSDK", "Selected provider is unavailable on this device")
}

Call setProvider() before requestAuthorization(). The SDK needs to know which provider to request permissions from.

Provider Comparison

Feature	Health Connect (`"google"`)	Samsung Health (`"samsung"`)
Device support	All Android 10+	Samsung devices only
Data types	25+ types	16 types
Pre-installed	Android 14+	Samsung devices
Install required	Play Store (Android < 14)	Samsung Health app

Health Connect is recommended as the default provider for the widest device and data type support.

Samsung Health SDK dependency

If you target Samsung Health, add Samsung’s own Health Data SDK (distributed as an .aar) to your app module. This is required to use the "samsung" provider at all - including in Developer Mode - not just for production. Download it from the Samsung Health Data SDK page:

// app/build.gradle.kts
dependencies {
    // Samsung Health Data SDK (downloaded from Samsung)
    implementation(files("libs/samsung-health-data-api.aar"))
}

Shipping Samsung Health to production requires Samsung’s approval. The permission flow is blocked at runtime until Samsung approves your partnership request and allowlists your release signing key. See Samsung Health Production Requirements before you plan a release.

Testing Samsung Health: Samsung Health is not available in the Android emulator - test on a physical Samsung device with the Samsung Health app installed. Before Samsung approves your app for production, enable Developer Mode in the Samsung Health app so the permission flow works on your test build. If setProvider("samsung") returns false, the device, the Samsung Health app, or Developer Mode is not set up.

Step 5: Request Permissions

Request access to specific health data types. The type IDs are string-based:

suspend fun requestHealthPermissions(): Boolean {
    val sdk = OpenWearablesHealthSDK.getInstance()

    val authorized = sdk.requestAuthorization(
        types = listOf(
            "steps",
            "heartRate",
            "restingHeartRate",
            "sleep",
            "workout",
            "activeEnergy",
            "bodyMass"
        )
    )

    if (authorized) {
        Log.d("HealthSDK", "Health permissions granted")
    } else {
        Log.d("HealthSDK", "Some permissions were denied")
    }

    return authorized
}

Make sure to call setActivity() on the SDK before requesting authorization, so the SDK can launch the permission dialog from the correct Activity context.

Step 6: Start Background Sync

Enable background sync to keep data flowing even when your app is in the background:

suspend fun startSync() {
    val sdk = OpenWearablesHealthSDK.getInstance()
    sdk.startBackgroundSync()
    Log.d("HealthSDK", "Background sync started: ${sdk.isSyncActive()}")
}

Controlling Sync History Depth

By default, the SDK syncs all available historical data on the first sync. Use the syncDaysBack parameter to limit how far back the sync goes:

// Sync only the last 90 days of data
sdk.startBackgroundSync(syncDaysBack = 90)

// Sync last 30 days
sdk.startBackgroundSync(syncDaysBack = 30)

// Full sync — all available history (default)
sdk.startBackgroundSync()

Parameter	Type	Default	Description
`syncDaysBack`	`Int?`	`null`	Number of days of historical data to sync. Syncs from the start of the day that many days ago. When `null`, syncs all available history. The value is persisted and used for subsequent background syncs until changed.

Background Sync Behavior

Mechanism	Description
WorkManager	Periodic background sync with system-managed scheduling
Foreground Service	Used during active sync for reliability (`health` type)
Notification	Shows a notification during active sync (Android 13+ requires permission)

Stop Sync

sdk.stopBackgroundSync()

Log Level

Control SDK log output using the logLevel property. By default, the SDK uses OWLogLevel.DEBUG, which outputs logs only in debuggable builds:

val sdk = OpenWearablesHealthSDK.getInstance()

// Always show logs (including release builds)
sdk.logLevel = OWLogLevel.ALWAYS

// Only show logs in debuggable builds (default)
sdk.logLevel = OWLogLevel.DEBUG

// Disable all logs
sdk.logLevel = OWLogLevel.NONE

Level	Description
`OWLogLevel.NONE`	No logs at all
`OWLogLevel.ALWAYS`	Logs are always emitted (Logcat + listener) regardless of build type
`OWLogLevel.DEBUG`	Logs are emitted only in debuggable builds (default)

Set OWLogLevel.ALWAYS during development or when troubleshooting sync issues in production. Switch to OWLogLevel.NONE if you want to suppress all SDK output.

Lifecycle Management

Notify the SDK of app lifecycle changes for optimal sync behavior:

class MainActivity : AppCompatActivity() {

    override fun onResume() {
        super.onResume()
        OpenWearablesHealthSDK.getInstance().onForeground()
    }

    override fun onPause() {
        super.onPause()
        OpenWearablesHealthSDK.getInstance().onBackground()
    }
}

Samsung Health Production Requirements

Samsung Health works on your development build with Developer Mode - for read access (what Open Wearables needs) you only need a Samsung account, no partnership request. Production adds a requirement: the same code runs, but the permission flow aborts on release builds until both of these are true:

Your partnership request is approved by Samsung. Submit it through Samsung’s app creation process, providing your app’s package name and release signing key signature.
Your release signing key is on Samsung’s allowlist. Samsung matches package name + SHA-256 at runtime. Get the fingerprint from your release keystore - and if you use Play App Signing, register the Play app signing key (Play Console → Setup → App integrity → App signing), not your upload key:
keytool -list -v -keystore release.keystore -alias your_release_alias

IllegalStateException: Could not get policy for {package} on a release build means Samsung has not matched your app - the partnership is not approved, or the running build’s package name or signing certificate does not match what Samsung registered (a common Play App Signing pitfall). Confirm all three, then contact Samsung Developer Support.

None of this applies to Health Connect ("google"), so you can ship with Health Connect first and add Samsung Health once approval lands.

Background sync

Samsung Health does not use the android.permission.health.* declarations Health Connect relies on - permissions are granted through Samsung Health’s own dialog, so no extra manifest permissions are needed for the Samsung provider. Background sync uses the same WorkManager and foreground-service mechanism as Health Connect; see Troubleshooting for the battery-optimization and POST_NOTIFICATIONS requirements that affect it.

Complete Integration Example

Here’s a complete ViewModel showing the full integration:

import androidx.lifecycle.ViewModel
import androidx.lifecycle.viewModelScope
import com.openwearables.health.sdk.OpenWearablesHealthSDK
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.launch

class HealthViewModel : ViewModel() {

    private val sdk = OpenWearablesHealthSDK.getInstance()

    private val _isConnected = MutableStateFlow(false)
    val isConnected: StateFlow<Boolean> = _isConnected

    private val _isSyncing = MutableStateFlow(false)
    val isSyncing: StateFlow<Boolean> = _isSyncing

    init {
        _isConnected.value = sdk.isSessionValid()
        _isSyncing.value = sdk.isSyncActive()
    }

    fun connect(userId: String, accessToken: String, refreshToken: String?) {
        viewModelScope.launch {
            try {
                // Sign in
                sdk.signIn(
                    userId = userId,
                    accessToken = accessToken,
                    refreshToken = refreshToken,
                    apiKey = null
                )

                // Set provider
                sdk.setProvider("google")

                // Request permissions
                val authorized = sdk.requestAuthorization(
                    types = listOf(
                        "steps", "heartRate", "sleep",
                        "workout", "activeEnergy"
                    )
                )

                if (authorized) {
                    sdk.startBackgroundSync(syncDaysBack = 90)
                }
            } catch (e: Exception) {
                Log.e("HealthSDK", "Connection failed", e)
            }
        }
    }

    fun disconnect() {
        viewModelScope.launch {
            sdk.stopBackgroundSync()
            sdk.signOut()
            _isConnected.value = false
            _isSyncing.value = false
        }
    }

    fun checkAndResumeSync() {
        viewModelScope.launch {
            if (sdk.hasResumableSyncSession()) {
                val status = sdk.getSyncStatus()
                Log.d("HealthSDK", "Resuming sync, sent: ${status["sentCount"]}")
                sdk.resumeSync()
            }
        }
    }

    fun resyncAllData() {
        viewModelScope.launch {
            sdk.stopBackgroundSync()
            sdk.resetAnchors()
            sdk.startBackgroundSync()
        }
    }

    override fun onCleared() {
        super.onCleared()
        sdk.destroy()
    }
}

Using the ViewModel

class HealthActivity : AppCompatActivity() {

    private val viewModel: HealthViewModel by viewModels()

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val sdk = OpenWearablesHealthSDK.getInstance()
        sdk.setActivity(this)

        // Observe state
        lifecycleScope.launch {
            viewModel.isConnected.collect { connected ->
                updateUI(connected)
            }
        }

        // Check for interrupted syncs
        viewModel.checkAndResumeSync()

        connectButton.setOnClickListener {
            val credentials = getCredentialsFromBackend()
            viewModel.connect(
                userId = credentials.userId,
                accessToken = credentials.accessToken,
                refreshToken = credentials.refreshToken
            )
        }

        disconnectButton.setOnClickListener {
            viewModel.disconnect()
        }
    }

    override fun onDestroy() {
        super.onDestroy()
        OpenWearablesHealthSDK.getInstance().setActivity(null)
    }
}

Data Sync Endpoint

The SDK sends health data to:

POST {host}/api/v1/sdk/users/{userId}/sync

The payload includes a provider field ("samsung" or "google") and the SDK version:

{
  "provider": "google",
  "sdkVersion": "0.12.0",
  "syncTimestamp": "2025-01-15T10:30:00Z",
  "data": {
    "records": [...],
    "workouts": [...],
    "sleep": [...]
  }
}

Data is automatically normalized to the Open Wearables unified data model and can be accessed through the standard API endpoints.

Getting started

Architecture

Health Scores

Providers

Open Wearables Mobile App

Mobile SDK

MCP Server

Developer Portal

Developer Guides

Configuration

Deployment

Support

Android Health Connect Integration Guide

Overview

Step 1: Backend Setup

Step 2: SDK Initialization & Configuration

Configuration Options

Session Restoration

Token-Based Authentication (Recommended)

API Key Authentication

Automatic Token Refresh

Step 4: Select Health Provider

Provider Comparison

Samsung Health SDK dependency

Step 5: Request Permissions

Step 6: Start Background Sync

Controlling Sync History Depth

Background Sync Behavior

Stop Sync

Log Level

Lifecycle Management

Samsung Health Production Requirements

Background sync

Complete Integration Example

Using the ViewModel

Data Sync Endpoint

Next Steps

Troubleshooting

Data Types

​Overview

​Step 1: Backend Setup

​Step 2: SDK Initialization & Configuration

​Configuration Options

​Session Restoration

​Step 3: Sign In

​Token-Based Authentication (Recommended)

​API Key Authentication

​Automatic Token Refresh

​Step 4: Select Health Provider

​Provider Comparison

​Samsung Health SDK dependency

​Step 5: Request Permissions

​Step 6: Start Background Sync

​Controlling Sync History Depth

​Background Sync Behavior

​Stop Sync

​Log Level

​Lifecycle Management

​Samsung Health Production Requirements

​Background sync

​Complete Integration Example

​Using the ViewModel

​Data Sync Endpoint

​Next Steps

Troubleshooting

Data Types

Overview

Step 1: Backend Setup

Step 2: SDK Initialization & Configuration

Configuration Options

Session Restoration

Step 3: Sign In

Token-Based Authentication (Recommended)

API Key Authentication

Automatic Token Refresh

Step 4: Select Health Provider

Provider Comparison

Samsung Health SDK dependency

Step 5: Request Permissions

Step 6: Start Background Sync

Controlling Sync History Depth

Background Sync Behavior

Stop Sync

Log Level

Lifecycle Management

Samsung Health Production Requirements

Background sync

Complete Integration Example

Using the ViewModel

Data Sync Endpoint

Next Steps