sensorkit

What this skill does

# SensorKit

Collect research-grade sensor data from iOS and watchOS devices for approved
research studies. SensorKit provides access to ambient light, motion, device
usage, keyboard metrics, visits, phone/messaging usage, speech metrics, face
metrics, wrist temperature, heart rate, ECG, and PPG data. Targets
Swift 6.3 / iOS 26+.

**SensorKit is restricted to Apple-approved research studies.** Apps must submit
a research proposal to Apple and receive the `com.apple.developer.sensorkit.reader.allow`
entitlement before any sensor data is accessible. This is not a general-purpose
sensor API -- use CoreMotion for ordinary accelerometer, gyroscope, pedometer,
or activity-recognition 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. **24-hour data hold** -- newly recorded data is inaccessible for 24 hours,
   giving users time to delete data they do not want to share.

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:

```xml
<key>com.apple.developer.sensorkit.reader.allow</key>
<array>
    <string>ambient-light-sensor</string>
    <string>motion-accelerometer</string>
    <string>motion-rotation-rate</string>
    <string>device-usage</string>
    <string>keyboard-metrics</string>
    <string>messages-usage</string>
    <string>phone-usage</string>
    <string>visits</string>
    <string>pedometer</string>
    <string>on-wrist</string>
    <string>speech-metrics-siri</string>
    <string>speech-metrics-telephony</string>
    <string>ambient-pressure</string>
    <string>ecg</string>
    <string>ppg</string>
</array>
```

Verify newer or specialized sensors against their individual `SRSensor` pages.
For example, Apple's ECG and PPG sensor pages explicitly require `ecg` and
`ppg` entitlement values in addition to their `NSSensorKitUsageDetail` entries.

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:

```xml
<!-- 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. Examples:
motion sensors use `SRSensorUsageMotion`, ambient pressure uses `SRSensorUsageElevation`,
ECG uses `SRSensorUsageECG`, PPG uses `SRSensorUsagePPG`, heart rate uses
`SRSensorUsageHeartRate`, and wrist temperature uses `SRSensorUsageWristTemperature`.

## Authorization

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

```swift
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)")
    }
}
```

Check a reader's current status before recording:

```swift
switch reader.authorizationStatus {
case .authorized:
    reader.startRecording()
case .denied:
    // User declined -- direct to Settings > Privacy > Research Sensor & Usage Data
    break
case .notDetermined:
    // Request authorization first
    break
@unknown default:
    break
}
```

Monitor status changes through the delegate:

```swift
func sensorReader(_ reader: SRSensorReader, didChange authorizationStatus: SRAuthorizationStatus) {
    switch authorizationStatus {
    case .authorized:
        reader.startRecording()
    case .denied:
        reader.stopRecording()
    default:
        break
    }
}
```

## Available Sensors

### Device Sensors

| Sensor | Type | Sample Type |
|---|---|---|
| `.deviceUsageReport` | Device usage | `SRDeviceUsageReport` |
| `.keyboardMetrics` | Keyboard activity | `SRKeyboardMetrics` |
| `.onWristState` | Watch wrist state | `SRWristDetection` |
| `.acousticSettings` | Acoustic/accessibility settings | `SRAcousticSettings` |

### App Activity Sensors

| Sensor | Type | Sample Type |
|---|---|---|
| `.messagesUsageReport` | Messages app usage | `SRMessagesUsageReport` |
| `.phoneUsageReport` | Phone call usage | `SRPhoneUsageReport` |

### User Activity Sensors

| Sensor | Type | Sample Type |
|---|---|---|
| `.accelerometer` | Acceleration data | `[CMRecordedAccelerometerData]` |
| `.rotationRate` | Rotation rate | `[CMRecordedRotationRateData]` |
| `.pedometerData` | Step/distance data | `CMPedometerData` |
| `.visits` | Visited locations | `SRVisit` |
| `.mediaEvents` | Media interactions | `SRMediaEvent` |
| `.faceMetrics` | Face expressions | `SRFaceMetrics` |
| `.heartRate` | Heart rate | `CMHighFrequencyHeartRateData` |
| `.odometer` | Speed/slope | `CMOdometerData` |
| `.siriSpeechMetrics` | Siri speech | `SRSpeechMetrics` |
| `.telephonySpeechMetrics` | Phone speech | `SRSpeechMetrics` |
| `.wristTemperature` | Wrist temp (sleep) | `SRWristTemperatureSession` |
| `.sleepSessions` | Sleep session summaries | `SRSleepSession` |
| `.photoplethysmogram` | PPG stream | `[SRPhotoplethysmogramSample]` |
| `.electrocardiogram` | ECG stream | `[SRElectrocardiogramSample]` |

### Environment Sensors

| Sensor | Type | Sample Type |
|---|---|---|
| `.ambientLightSensor` | Ambient light | `SRAmbientLightSample` |
| `.ambientPressure` | Pressure/temp | `[CMRecordedPressureData]` |

## SRSensorReader

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

```swift
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
keyboardReader.delegate = self
```

The reader communi