> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/mobile-sdks/samsung-health.md).

# Samsung Health

Read Samsung Health data with the Android SDK, through Health Connect or directly with the Samsung add-on.

There are two ways to get Samsung Health data into Terra with the [Android SDK](https://docs.tryterra.co/mobile-sdks/android-sdk-2.md). This page compares them and shows how to set up each one.

* **Through Health Connect.** Samsung Health writes most of its data into Health Connect, and the core SDK reads it as `Source.HEALTH`. Nothing extra to install.
* **Directly.** The [`terra-android-samsung`](https://docs.tryterra.co/reference/mobile-sdks/android-sdk-2#samsung-health-add-on) add-on reads Samsung Health's own store as [`Source.SAMSUNG_HEALTH`](https://docs.tryterra.co/reference/mobile-sdks/android-sdk-2#source), through Samsung's Health Data SDK.

## Choose a route

|                         | Through Health Connect                                                            | Directly (add-on)                                                                        |
| ----------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Setup                   | Core SDK only                                                                     | Add-on, plus Samsung's SDK that you download, plus Samsung partner approval for your app |
| Devices                 | Any Android phone with Health Connect                                             | Phones with Samsung Health, Android 10 (API 29) or later                                 |
| Other apps' data        | Yes, everything in Health Connect                                                 | No, only what Samsung Health recorded itself                                             |
| Samsung Health workouts | Only the ones Samsung Health copies into Health Connect, which is not all of them | All of them                                                                              |
| Time to ship            | Now                                                                               | After Samsung approves your app                                                          |

Start with Health Connect. It covers most Samsung users with no extra approval. Add the direct route when you need every Samsung Health workout, or Samsung data Health Connect does not carry.

## Read through Health Connect

Follow the [Android SDK](https://docs.tryterra.co/mobile-sdks/android-sdk-2.md) guide and connect `Source.HEALTH`. Samsung Health's data arrives with everything else in Health Connect.

The person has to allow Samsung Health to share its data with Health Connect, in Samsung Health's settings.

## Read directly with the add-on

### Register your app with Samsung

Every app that reads Samsung Health directly must be registered with Samsung under its own package name. Samsung approves each package separately, so Terra's registration does not cover your app.

1. Submit a partner request to Samsung with your app's **package name** and the **SHA-256 fingerprint** of its signing certificate. If your app is already approved for Samsung's older Samsung Health SDK for Android, that approval does not carry over. Submit Samsung's migration partner request from your existing Samsung developer account. See Samsung's [migration guide](https://developer.samsung.com/health/data/migration-guide/overview.html).
2. Until Samsung approves it, reads only work with Samsung Health's **developer mode** turned on: in Samsung Health, open **Settings > About Samsung Health** and tap the version number repeatedly. Developer mode is for testing only. Your users will not have it.

### Download Samsung's SDK

1. Sign in at [Samsung Health Data SDK](https://developer.samsung.com/health/data/overview.html) and download **version 1.1.0**. It is the only version the add-on supports.
2. Unpack it and copy `samsung-health-data-api.aar` into your app module's `libs/` folder.

### Add the dependencies

{% code title="app/build.gradle.kts" %}

```kotlin
plugins {
    id("kotlin-parcelize")
}

dependencies {
    implementation("co.tryterra:terra-android:2.3.0")
    implementation("co.tryterra:terra-android-samsung:2.3.0")

    // Samsung's SDK, which your app packages
    implementation(files("libs/samsung-health-data-api.aar"))
    // Samsung's SDK needs both at runtime and does not bring them
    implementation("com.google.code.gson:gson:2.11.0")
    implementation("org.jetbrains.kotlin:kotlin-parcelize-runtime:<your Kotlin version>")
}
```

{% endcode %}

### Register the store

Register the Samsung store when you build `Terra`:

{% code title="YourApp.kt" %}

```kotlin
import co.tryterra.sdk.health.samsung.samsungHealth

terra = Terra(
    this,
    devId = BuildConfig.TERRA_DEV_ID,
    tokenProvider = { yourBackend.mintTerraToken() },
) {
    samsungHealth()
}
BackgroundSync.register(this, terra)
```

{% endcode %}

### Connect and request permissions

Samsung Health has its own permission sheet, so it has its own launcher. Reach it through [`terra.on(Source.SAMSUNG_HEALTH)`](https://docs.tryterra.co/reference/mobile-sdks/android-sdk-2#terra.on):

{% code title="ConnectActivity.kt" %}

```kotlin
// in onCreate
samsungLauncher = terra.on(Source.SAMSUNG_HEALTH).permissions.launcher(this)

// on tap
terra.connect(Source.SAMSUNG_HEALTH, EndUser.Reference(signedInUser.id))
terra.on(Source.SAMSUNG_HEALTH).permissions.request(
    read = setOf(DataCategory.DAILY, DataCategory.SLEEP, DataCategory.ACTIVITY),
    launcher = samsungLauncher,
)
```

{% endcode %}

From here it behaves like Health Connect: the same triggers, the same two-year first sync, and the same background runs. The token provider is called for the Samsung link the same way.

The Samsung store reads only. It does not write to Samsung Health.

Samsung Health is requested by category only. A request that passes `readTypes` for `Source.SAMSUNG_HEALTH` throws `IllegalArgumentException` before anything is recorded or shown. To ask for [individual types](https://docs.tryterra.co/mobile-sdks/android-sdk-2.md#request-individual-types), read Samsung Health's data through Health Connect instead.

## Use both routes

An app can connect `Source.HEALTH` and `Source.SAMSUNG_HEALTH` on the same phone.

* **The Samsung store uploads only what Samsung Health recorded itself.** Data Samsung Health imported from other apps is left to Health Connect.
* **The Health Connect store uploads everything else.** The Samsung store takes precedence by default, and Health Connect fills in the gaps.

The SDK checks every record type on every read. If the Samsung store can no longer send a record type, for example because the user withdrew access, disconnected, or uninstalled Samsung Health, the SDK automatically falls back to Health Connect. Record types the Samsung store does not read as records, such as resting heart rate, HRV, respiratory rate, steps, energy, distance and floors, always stay with Health Connect.

{% hint style="warning" %}
**Day totals are not de-duplicated.** Health Connect cannot leave one app out of its daily totals, so its daily steps, energy, distance and floors include Samsung Health's. Samsung's daily totals are the whole device's figure too. A user connected through both may show the same steps in both daily totals, each under its own source. Individual records are never sent twice.
{% endhint %}

If you want the SDK to send readings from both Health Connect and the Samsung store, including the records they share, register the store with `samsungHealth(dedupeHealthConnect = false)`.

{% hint style="info" %}
**The mobile SDKs are only for Apple Health, Health Connect and Samsung Health.** These have no web API, so your app reads them on the phone and sends the data to Terra. Every other provider connects through the [Unified API](https://docs.tryterra.co/unified-api/getting-started) with no SDK.
{% endhint %}

## Next steps

* [React Native SDK](https://docs.tryterra.co/mobile-sdks/react-native-sdk-2.md): connect Apple Health and Health Connect from one codebase.
* [Health data events](https://docs.tryterra.co/unified-api/receiving-data-updates.md): handle the data the SDK uploads.
