/sensorkit

name: sensorkit
description: "Access research-grade sensor data using SensorKit for approved studies. Use when an app needs SensorKit entitlement setup, Research Sensor & Usage Data authorization, ambient light, recorded motion, device usage, keyboard metrics, visits, speech, face, wrist temperature, ECG, PPG, acoustic settings, or sleep-session data. Route ordinary motion to CoreMotion and health records/workouts to HealthKit."

SensorKit

Choose the exact `SRSensor` and verify its individual availability. Use CoreMotion for ordinary motion/activity features and HealthKit for health records and workouts.

Contents

• [Overview and Requirements](#overview-and-requirements)
• [Entitlements](#entitlements)
• [Info.plist Configuration](#infoplist-configuration)
• [Authorization](#authorization)
• [Available Sensors](#available-sensors)
• [SRSensorReader](#srsensorreader)
• [Recording and Fetching Data](#recording-and-fetching-data)
• [SRDevice](#srdevice)
• [Common Mistakes](#common-mistakes)
• [Review Checklist](#review-checklist)
• [References](#references)

Overview and Requirements

SensorKit enables research apps to record and fetch sensor data across iPhone and Apple Watch. The framework requires:

1. **Apple-approved research study** -- submit a proposal at [researchandcare.org](https://www.researchandcare.org/resources/accessing-sensorkit-data/). 2. **SensorKit entitlement** -- Apple grants `com.apple.developer.sensorkit.reader.allow` only for approved studies. 3. **Manual provisioning profile** -- Xcode requires an explicit App ID with the SensorKit capability enabled. 4. **User authorization** -- the system presents a Research Sensor & Usage Data sheet that users approve per-sensor. 5. **Delayed retrieval** -- design fetch timing around the canonical [Data Holding Period](#data-holding-period).

An app can access up to 7 days of prior recorded data for an active sensor.

Entitlements

Add the SensorKit reader entitlement to a `.entitlements` file. List only the sensors Apple approved for the study. Common entitlement values include:

<key>com.apple.developer.sensorkit.reader.allow</key>
<array>
    <string>ambient-light-sensor</string>
    <string>motion-accelerometer</string>
    <string>device-usage</string>
    <string>keyboard-metrics</string>
</array>

Load the [Entitlement and Usage-Detail Catalog](references/sensorkit-patterns.md#entitlement-and-usage-detail-catalog) when selecting the exact entitlement string and `NSSensorKitUsageDetail` key for each approved sensor. Recheck specialized sensors against their individual `SRSensor` pages.

For manual signing, set Code Signing Entitlements to the entitlements file, Code Signing Identity to `Apple Developer`, Code Signing Style to `Manual`, and Provisioning Profile to the explicit profile with SensorKit capability.

Info.plist Configuration

Three keys are required:

<!-- Study purpose shown in the authorization sheet -->
<key>NSSensorKitUsageDescription</key>
<string>This study monitors activity patterns for sleep research.</string>

<!-- Link to your study's privacy policy -->
<key>NSSensorKitPrivacyPolicyURL</key>
<string>https://example.com/privacy-policy</string>

<!-- Per-sensor usage explanations -->
<key>NSSensorKitUsageDetail</key>
<dict>
    <key>SRSensorUsageMotion</key>
    <dict>
        <key>Description</key>
        <string>Measures physical activity levels during the study.</string>
        <key>Required</key>
        <true/>
    </dict>
    <key>SRSensorUsageAmbientLightSensor</key>
    <dict>
        <key>Description</key>
        <string>Records ambient light to assess sleep environment.</string>
    </dict>
</dict>

If `Required` is `true` and the user denies that sensor, the system warns them that the study needs it and offers a chance to reconsider.

Use the exact usage-detail dictionary for each requested sensor. Load the [Entitlement and Usage-Detail Catalog](references/sensorkit-patterns.md#entitlement-and-usage-detail-catalog) when mapping sensors beyond the motion and ambient-light examples above.

Authorization

Request authorization for the sensors your study needs. The system shows the Research Sensor & Usage Data sheet on first request.

import SensorKit

let reader = SRSensorReader(sensor: .ambientLightSensor)

// Request authorization for multiple sensors at once
SRSensorReader.requestAuthorization(
    sensors: [.ambientLightSensor, .accelerometer, .keyboardMetrics]
) { error in
    if let error {
        print("Authorization request failed: \(error)")
    }
}

Use one status handler both for the initial check and delegate changes:

private func applyAuthorizationStatus(
    _ status: SRAuthorizationStatus,
    to reader: SRSensorReader
) {
    switch status {
    case .authorized:
        reader.startRecording()
    case .denied:
        reader.stopRecording()
        // Direct the user to Settings > Privacy > Research Sensor & Usage Data.
    case .notDetermined:
        break // Request authorization first.
    @unknown default:
        break
    }
}

applyAuthorizationStatus(reader.authorizationStatus, to: reader)

func sensorReader(_ reader: SRSensorReader, didChange authorizationStatus: SRAuthorizationStatus) {
    applyAuthorizationStatus(authorizationStatus, to: reader)
}

Available Sensors

Load the [Sensor Catalog](references/sensorkit-patterns.md#sensor-catalog) to map each `SRSensor` to its sample type. Request only sensors approved for the study and recheck the selected sensor's availability and usage-detail key.

SRSensorReader

`SRSensorReader` is the central class for accessing sensor data. Each instance reads from a single sensor.

import SensorKit

// Create a reader for one sensor
let lightReader = SRSensorReader(sensor: .ambientLightSensor)
let keyboardReader = SRSensorReader(sensor: .keyboardMetrics)

// Assign delegate to receive callbacks
lightReader.delegate = self
key