Installation

Install the Circadify Android SDK in a native Kotlin Android app.

The Circadify Android SDK is a native Kotlin Android library for contactless vital sign measurement. Your app owns the UI, camera permission prompt, preview surface, and overlays. The SDK handles camera capture, scan quality checks, secure upload, and result polling.

Before you start

You need two separate credentials from Circadify, both self-serve from the developer portal:

1. A Circadify access token — authenticates the download of the SDK package from sdk.circadify.com/maven/. This page (Steps 1–2 and Gradle setup) covers getting and using it.
2. An API key (ck_live_ or ck_test_) — authenticates the SDK at runtime when it takes measurements. Covered under Get an API Key below.

They are different tokens with different jobs — the access token gets you the package, the API key runs the SDK. You do not need a GitHub account or GitHub PAT for the Android SDK; the same Circadify access token also installs the Web, React, and iOS SDKs.

Step 1 — Request and retrieve your access token

com.circadify:circadify-android-sdk is distributed from https://sdk.circadify.com/maven/ and requires authentication. Gradle authenticates with HTTP Basic auth using your developer account email and your Circadify access token.

Step 2 — Make your credentials available to Gradle

The Gradle setup below reads your email and token from environment variables (CIRCADIFY_MAVEN_USER / CIRCADIFY_MAVEN_TOKEN), with a gradle.properties fallback. Pick one of the two methods below.

Option A — environment variables

For local development, add these to your shell profile (~/.zshrc, ~/.bashrc, or ~/.bash_profile):

export CIRCADIFY_MAVEN_USER=<your-developer-account-email>
export CIRCADIFY_MAVEN_TOKEN=<your-circadify-access-token>

Then reload your shell so Gradle sees them (e.g. source ~/.zshrc). Replace <your-developer-account-email> with the email you signed up with at developer.circadify.com, and <your-circadify-access-token> with the token from Step 1.

Option B — ~/.gradle/gradle.properties

If you prefer not to export environment variables, store the credentials in ~/.gradle/gradle.properties (in your home directory, outside your project):

circadifyMavenUser=<your-developer-account-email>
circadifyMavenToken=<your-circadify-access-token>

The Gradle snippet below falls back to these properties when the environment variables aren't set.

Gradle setup

Add the Circadify Maven repository:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven("https://sdk.circadify.com/maven/") {
            credentials {
                // Reads the env vars from Step 2 Option A, falling back to the
                // circadifyMavenUser / circadifyMavenToken gradle.properties from Option B.
                username = System.getenv("CIRCADIFY_MAVEN_USER")
                    ?: providers.gradleProperty("circadifyMavenUser").orNull
                password = System.getenv("CIRCADIFY_MAVEN_TOKEN")
                    ?: providers.gradleProperty("circadifyMavenToken").orNull
            }
            authentication {
                create<BasicAuthentication>("basic")
            }
            content {
                includeGroup("com.circadify")
            }
        }
    }
}

Add the SDK dependency to your app module:

dependencies {
    implementation("com.circadify:circadify-android-sdk:0.1.2")
}

Manifest

The host app must declare camera and internet access. Mark camera hardware as optional unless every install target must have a camera.

<uses-feature android:name="android.hardware.camera" android:required="false" />
 
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.INTERNET" />

Get an API Key

This is the second credential introduced in Before you start, and it is separate from the access token Gradle used to download the package. The access token authenticates the download; an API key authenticates the SDK at runtime when it takes measurements.

Get an API key from the Keys page in the developer portal. (This is a different credential from the SDK access token in Step 1 — the access token downloads the SDK package; the API key authorizes the SDK at runtime.) Keys come in two formats, distinguished by their prefix: ck_live_ (production — real measurements, counts against your plan) and ck_test_ (sandbox — deterministic simulated vitals, free, never billed). Pass it when you initialize the SDK; read it from a secret or environment variable rather than hardcoding it. See Configuration for initialization and Authentication for key details.

Requirements

Next Steps

• Configuration - Initialize the SDK and register callbacks
• Performance & Device Support - Capture policy and lower-end device guidance
• Camera & Permissions - Request camera access correctly
• Methods - Start, cancel, and clean up measurements