Circadify

Installation

Install the Circadify rPPG SDK for iOS. Capture heart rate, HRV, respiratory rate, and configured outputs from the iPhone camera. Swift 5.10+, iOS 17+.

Requirements

RequirementMinimum
iOS17.0+
Swift5.10+
Xcode15.3+
DevicePhysical device with a camera (front or back)
Caution

The iOS SDK requires a physical device with a camera. The iOS Simulator does not support camera capture and cannot run measurements.

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. This page (Steps 1–3) 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 iOS SDK; the same Circadify access token also installs the Web, React, and Android SDKs.

Migrating from GitHub Packages

Already installing the iOS SDK from a private GitHub repo with a GitHub PAT? That still works for now — nothing breaks today. To move to the new setup, change your Swift Package Manager package URL to https://sdk.circadify.com/ios/circadify-ios-sdk.git and add the new sdk.circadify.com credential (via ~/.netrc or the macOS Keychain — see Step 2). Your old github.com Git credential / PAT is no longer needed and can be removed once the new setup resolves successfully. Switch when convenient. (Web and React now install the same way — from sdk.circadify.com with this one Circadify access token.)

Note

Throughout this page, your username is your developer account email — the email you signed up with at developer.circadify.com — and your password is your Circadify access token. This is not a GitHub login, App Store credential, or certificate password.

Step 1 — Request and retrieve your access token

circadify-ios-sdk is distributed from https://sdk.circadify.com/ios/circadify-ios-sdk.git. Swift Package Manager fetches it over Git, so you need a Circadify access token before you can resolve it.

  1. Request SDK access. Go to the developer portal and request SDK access with the email you want to install from. Approval is self-serve and typically lands within 24 hours.

  2. Retrieve your token. Once approved, open Integrate → iOS in the developer portal. Your Circadify access token and ready-to-paste install snippets appear inline in the SDK Access panel. The token isn't a one-time secret — you can return to this page anytime to copy it again or check its status. (If the panel still shows your request as pending, you'll get an email when it's approved, or contact support@circadify.com.)

Note

All four SDKs — Web, React, iOS, and Android — install from sdk.circadify.com using this one Circadify access token — the same token works for every platform. The token is revocable — to rotate or revoke it, use the developer portal or email support@circadify.com.

Step 2 — Authenticate Swift Package Manager

Pick one of the two methods below — you do not need both. In each, the username is your developer account email and the password is your Circadify access token.

Option A — macOS Keychain via Xcode (recommended)

When Xcode first tries to resolve the package it prompts for credentials. You can also add them ahead of time:

  1. Open Xcode → Settings → Accounts.
  2. Click +, choose Git (not GitHub), and pick Add a Git host account.
  3. For Host, enter sdk.circadify.com; for User name, enter your developer account email; for Password, paste your Circadify access token (not a GitHub PAT).

Xcode caches these in the Keychain and uses them to resolve the private package automatically on the next build.

Option B — ~/.netrc (command line / CI)

Create or edit a git-ignored ~/.netrc so Git can authenticate non-interactively:

machine sdk.circadify.com
  login <your-developer-account-email>
  password <your-circadify-access-token>

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. Keep .netrc out of source control.

Then restrict its permissions:

chmod 600 ~/.netrc

Locking the file down is security hygiene — the token in it grants SDK downloads on your account — and some tools are also stricter about permissive .netrc files.

Step 3 — Install via Swift Package Manager

  1. In Xcode, go to File → Add Package Dependencies...

  2. Enter the repository URL:

    https://sdk.circadify.com/ios/circadify-ios-sdk.git

  3. Select Up to Next Major Version and set the minimum to 0.1.2.

  4. Click Add Package and add CircadifySDK to your target.

Or add it directly to your Package.swift:

dependencies: [
    .package(url: "https://sdk.circadify.com/ios/circadify-ios-sdk.git", from: "0.1.2")
]
swift
Note

MediaPipe and other native dependencies are public and download automatically from downloads.circadify.com — they need no authentication.

Required linker flags

CircadifySDK links MediaPipe, whose graph calculators register themselves via C++ static initializers. Add -ObjC and -all_load to your app target's Other Linker Flags (OTHER_LDFLAGS):

OTHER_LDFLAGS = $(inherited) -ObjC -all_load

In Xcode: select your app target → Build Settings → search Other Linker Flags → add -ObjC and -all_load.

Caution

Without these flags the project still builds, but the first scan crashes at runtime with "Unable to find Calculator FaceLandmarkerGraph." They can't be set inside the package — Swift Package Manager won't resolve a package by version when its manifest uses unsafe build flags — so the consuming app must set them.

Camera Permission

Add the camera usage description to your Info.plist:

<key>NSCameraUsageDescription</key>
<string>This app uses the camera to measure your vital signs contactlessly.</string>
xml

Without this entry, iOS will terminate your app when the SDK attempts to access the camera.

Get an API Key

This is the second credential introduced in Before you start, and it is separate from the access token you 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). The prefix alone determines behavior on the server. See Authentication for details.

Verify Installation

Initialize the SDK with your API key (not your access token). Read the key from your environment rather than hardcoding it:

import CircadifySDK
 
// Read your key from the environment — never hardcode it in source.
let sdk = try CircadifySDK(
    apiKey: ProcessInfo.processInfo.environment["CIRCADIFY_API_KEY"] ?? "ck_test_your_key_here"
)
print("SDK initialized")
swift

If this compiles and runs without error, the SDK is installed correctly. Use a ck_test_ key here to verify against the free sandbox without burning production quota.

Next Steps