Skip to main content

Quick Start

Get started with the basic implementation

1. Overview​

Features​

  • Get authorization.
  • Register users.
  • Sync Samsung Health summaries and events.
  • Schedule automatic Samsung Health data syncs in background.

Restrictions​

  • Samsung Health Data SDK requires Samsung Health v6.29 or later version installation.
  • Samsung Health runs on devices with Android 10 (API level 29) or above. It is available on all Samsung smartphones and also non-Samsung Android smartphones.
  • The SDK doesn’t support an emulator.

Android Studio​

Android Studio Narwhal 4 Feature Drop | 2025.1.4 or higher is recommended.

2. Installation​

In your build.gradle (app) set your min and target sdk version like below:

minSdk 29
targetSdk 36

In your build.gradle (app module) add the required dependencies.

Copy the samsung-health-data.aar file to your project libs directory:

  • Latest version: Maven Central Version
  • Latest stable version: 4.0.0
  • LTS version (supported until September 27, 2026): 1.1.0
dependencies {
    implementation("io.tryrook.android:rook-sdk-samsung:version")
    implementation(files("$rootDir/libs/samsung-health-data-api-1.0.0.aar"))

    // Used by Samsung Health Data AAR:
    implementation("com.google.code.gson:gson:2.13.2")
}

Apply the Kotlin parcelize plugin to your app module:

[versions]
kotlin = "2.1.21"

[plugins]
org-jetbrains-kotlin-plugin-parcelize = { id = "org.jetbrains.kotlin.plugin.parcelize", version.ref = "kotlin" }
plugins {
    alias(libs.plugins.org.jetbrains.kotlin.plugin.parcelize)
}

Enable developer mode on your device.

3. Initialize SDK​

val environment = if (BuildConfig.DEBUG) SHEnvironment.SANDBOX else SHEnvironment.PRODUCTION
val configuration = SHConfiguration(clientUUID, secret, environment)

// Enable logging only on debug builds
if (BuildConfig.DEBUG) {
    rookSamsung.enableLocalLogs()
}

rookSamsung.initRook(configuration).fold(
    {
        // Success
    },
    {
        // Handle error
    }
)
tip

RookSamsungObject is an alternative to the RookSamsung class that does not require an instance, however you'll need to provide a context with every function call:

tip

You should only initialize the SDK once per app launch.

Critical Requirement

You must register your applicationId (package name) and its corresponding secret in the ROOK Portal before attempting to initialize the SDK. Failure to register these credentials will cause the initialization to fail with an SHNotAuthorizedException.

The ROOK Portal supports independent configurations for Sandbox and Production environments. Each environment requires its own unique pair of Package Name and secret

If you come from a previous version you MUST re-initialize the SDK with the new authentication flow.

val configuration = SHConfiguration(clientUUID, secretKey, environment)

// RookSamsung
val rookSamsung = RookSamsung(applicationContext)
rookSamsung.initRook(configuration)

// RookSamsungObject
RookSamsungObject.initRook(applicationContext, configuration)

:::

4. Update userID​

Update the userID:

rookSamsung.updateUserID(userID).fold(
    {
        // Success
    },
    {
        // Handle error
    }
)
info

Any call to updateUserID with a different userID will override the previous userID and reset the sync status, so if you are using Automatic Sync all health data will synchronize again.

5. Request permissions​

Check availability​

Before requesting permissions check that Samsung Health is installed and ready to be used:

rookSamsung.checkSamsungHealthAvailability().fold(
    { availability ->
        // Success
    },
    {
        // Hanlde errors
    },
)

Once you have confirmed that availability == SamsungHealthAvailability.INSTALLED, ask permissions:

val samsungPermissions: Set<SamsungHealthPermission> = setOf(
    SamsungHealthPermission.ACTIVITY_SUMMARY,
    SamsungHealthPermission.BLOOD_GLUCOSE,
    SamsungHealthPermission.BLOOD_OXYGEN,
    SamsungHealthPermission.BLOOD_PRESSURE,
    SamsungHealthPermission.BODY_COMPOSITION,
    SamsungHealthPermission.EXERCISE,
    SamsungHealthPermission.EXERCISE_LOCATION,
    SamsungHealthPermission.FLOORS_CLIMBED,
    SamsungHealthPermission.HEART_RATE,
    SamsungHealthPermission.NUTRITION,
    SamsungHealthPermission.SLEEP,
    SamsungHealthPermission.STEPS,
    SamsungHealthPermission.WATER_INTAKE,
)

rookSamsung.requestSamsungHealthPermissions(samsungPermissions).fold(
    {
        when (it) {
            SHRequestPermissionsStatus.ALREADY_GRANTED -> {
                // Permissions already granted, update your UI
            }

            SHRequestPermissionsStatus.REQUEST_SENT -> {
                // Permissions dialog has been displayed
            }
        }
    },
    {
        // Handle error
    }
)

6. Schedule a background sync​

rookSamsung.schedule(enableLogs = isDebug)
tip

We recommend adding an extra call to schedule in the onCreate callback of your Application class:

class MyAplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // It's a good practice to ask your users if they want to enable this behaviour
        // and wrap this line inside an if which checks a preferences-stored flag
        if (userAllowedBackgroundSync) {
            RookSamsungObject.schedule(this, enableLogs = isDebug)
        }
    }
}

Continue learning​

Next steps​

Prepare for release​

Additional resources​