SensorKit
Access granular ambient, motion, biometric, and interaction sensor streams for approved research and clinical studies using SRSensorReader. Targets Swift 6.4 / iOS 26+.
Entitlement Warning: SensorKit requires Apple entitlement approval (com.apple.developer.sensorkit.reader.allow). SensorKit cannot be tested on standard consumer apps or simulators without approved research provisioning.
Contents
Setup & Entitlements
- Obtain the research entitlement
com.apple.developer.sensorkit.reader.allow from Apple.
- Add sensor usage descriptions to Info.plist corresponding to each queried sensor (e.g.
NSSensorKitUsageDescription, NSSensorKitUsageDescriptionAmbientLightSensor).
- Request authorization explicitly before instantiating readers:
import SensorKit
func requestSensorAccess(for sensors: Set<SRSensor>) async {
let status = await SRSensorReader.requestAuthorization(for: sensors)
// Handle authorization response
}
Sensor Reader Lifecycle
Create an SRSensorReader per sensor type and assign an SRSensorReaderDelegate:
final class AmbientLightCollector: NSObject, SRSensorReaderDelegate {
private let reader = SRSensorReader(sensor: .ambientLightSensor)
override init() {
super.init()
reader.delegate = self
}
func start() {
guard reader.authorizationStatus == .authorized else { return }
reader.startRecording()
}
func stop() {
reader.stopRecording()
}
}
Fetching Sensor Data
Query historical recorded samples by date interval:
func fetchSamples(from start: SRAbsoluteTime, to end: SRAbsoluteTime) {
let request = SRFetchRequest()
request.from = start
request.to = end
reader.fetch(request)
}
// SRSensorReaderDelegate
func sensorReader(_ reader: SRSensorReader, fetching request: SRFetchRequest, didFetchResult result: SRFetchResult) -> Bool {
if let sample = result.sample as? SRAmbientLightSample {
// Process sensor sample
}
return true // Return true to continue fetching remaining results
}
func sensorReader(_ reader: SRSensorReader, didCompleteFetch request: SRFetchRequest) {
// Finished fetch
}
Available Sensor Categories
- Motion & Environment:
.ambientLightSensor, .accelerometer, .rotationRate, .elevation.
- User Interactions:
.keyboardMetrics, .deviceUsageReport, .messagesUsageReport, .phoneUsageReport.
- Physiological & Health:
.speechMetrics, .faceMetrics, .wristTemperature, .heartRate.
Data Deletion & User Privacy
Research participants can delete recorded data. Honor deletion requests via SRSensorReader:
func purgeData(before timestamp: SRAbsoluteTime) async throws {
let request = SRDeletionRequest()
request.endTime = timestamp
try await reader.delete(request)
}
Common Mistakes
- Shipping without Apple entitlement approval: SensorKit APIs fail immediately unless signed with an approved provisioning profile.
- Returning false in fetch delegate prematurely: Returning
false from didFetchResult halts subsequent sample delivery.
- Forgetting per-sensor usage descriptions: Each sensor type requires its dedicated Info.plist explanation key.
- Querying unbounded time intervals: Always constrain
SRFetchRequest to bounded start and end timestamps to avoid memory exhaustion.
- Assuming simulator support: SensorKit does not record or simulate hardware sensor streams on iOS Simulator.
Review Checklist
References
- Setup, sensor/delegate catalogs, and multi-sensor manager
- Keyboard, device, phone, visit, media, and wrist samples
- Speech, face, temperature, ECG/PPG, deletion, and testing
- SensorKit framework
- SRSensorReader
- SRSensor
- SRDevice
- SRFetchRequest
- Configuring your project for sensor reading
- com.apple.developer.sensorkit.reader.allow
1---2name: sensorkit3description: "Access ambient, motion, biometric, and interaction research data using SensorKit. Use when configuring sensor readers, handling authorization and study onboarding, fetching sample streams, managing user data deletion, or building research and clinical studies."4metadata:5 source: https://skillmd.com/skills/thiennc-tesoglobal/sensorkit6---78# SensorKit910Access granular ambient, motion, biometric, and interaction sensor streams for approved research and clinical studies using `SRSensorReader`. Targets Swift 6.4 / iOS 26+.1112> **Entitlement Warning:** SensorKit requires Apple entitlement approval (`com.apple.developer.sensorkit.reader.allow`). SensorKit cannot be tested on standard consumer apps or simulators without approved research provisioning.1314## Contents1516- [Setup & Entitlements](#setup--entitlements)17- [Sensor Reader Lifecycle](#sensor-reader-lifecycle)18- [Fetching Sensor Data](#fetching-sensor-data)19- [Available Sensor Categories](#available-sensor-categories)20- [Data Deletion & User Privacy](#data-deletion--user-privacy)21- [Common Mistakes](#common-mistakes)22- [Review Checklist](#review-checklist)23- [References](#references)2425## Setup & Entitlements26271. Obtain the research entitlement `com.apple.developer.sensorkit.reader.allow` from Apple.282. Add sensor usage descriptions to Info.plist corresponding to each queried sensor (e.g. `NSSensorKitUsageDescription`, `NSSensorKitUsageDescriptionAmbientLightSensor`).293. Request authorization explicitly before instantiating readers:3031```swift32import SensorKit3334func requestSensorAccess(for sensors: Set<SRSensor>) async {35 let status = await SRSensorReader.requestAuthorization(for: sensors)36 // Handle authorization response37}38```3940## Sensor Reader Lifecycle4142Create an `SRSensorReader` per sensor type and assign an `SRSensorReaderDelegate`:4344```swift45final class AmbientLightCollector: NSObject, SRSensorReaderDelegate {46 private let reader = SRSensorReader(sensor: .ambientLightSensor)4748 override init() {49 super.init()50 reader.delegate = self51 }5253 func start() {54 guard reader.authorizationStatus == .authorized else { return }55 reader.startRecording()56 }5758 func stop() {59 reader.stopRecording()60 }61}62```6364## Fetching Sensor Data6566Query historical recorded samples by date interval:6768```swift69func fetchSamples(from start: SRAbsoluteTime, to end: SRAbsoluteTime) {70 let request = SRFetchRequest()71 request.from = start72 request.to = end7374 reader.fetch(request)75}7677// SRSensorReaderDelegate78func sensorReader(_ reader: SRSensorReader, fetching request: SRFetchRequest, didFetchResult result: SRFetchResult) -> Bool {79 if let sample = result.sample as? SRAmbientLightSample {80 // Process sensor sample81 }82 return true // Return true to continue fetching remaining results83}8485func sensorReader(_ reader: SRSensorReader, didCompleteFetch request: SRFetchRequest) {86 // Finished fetch87}88```8990## Available Sensor Categories9192- **Motion & Environment**: `.ambientLightSensor`, `.accelerometer`, `.rotationRate`, `.elevation`.93- **User Interactions**: `.keyboardMetrics`, `.deviceUsageReport`, `.messagesUsageReport`, `.phoneUsageReport`.94- **Physiological & Health**: `.speechMetrics`, `.faceMetrics`, `.wristTemperature`, `.heartRate`.9596## Data Deletion & User Privacy9798Research participants can delete recorded data. Honor deletion requests via `SRSensorReader`:99100```swift101func purgeData(before timestamp: SRAbsoluteTime) async throws {102 let request = SRDeletionRequest()103 request.endTime = timestamp104 try await reader.delete(request)105}106```107108## Common Mistakes109110- **Shipping without Apple entitlement approval**: SensorKit APIs fail immediately unless signed with an approved provisioning profile.111- **Returning false in fetch delegate prematurely**: Returning `false` from `didFetchResult` halts subsequent sample delivery.112- **Forgetting per-sensor usage descriptions**: Each sensor type requires its dedicated Info.plist explanation key.113- **Querying unbounded time intervals**: Always constrain `SRFetchRequest` to bounded start and end timestamps to avoid memory exhaustion.114- **Assuming simulator support**: SensorKit does not record or simulate hardware sensor streams on iOS Simulator.115116## Review Checklist117118- [ ] `com.apple.developer.sensorkit.reader.allow` entitlement confirmed active119- [ ] Required sensor usage descriptions declared in Info.plist120- [ ] `requestAuthorization(for:)` called before starting reader recording121- [ ] `didFetchResult` returns `true` while iterating batch samples122- [ ] Deletion requests supported for participant privacy compliance123124## References125126- [Setup, sensor/delegate catalogs, and multi-sensor manager](references/setup-catalog-and-manager.md)127- [Keyboard, device, phone, visit, media, and wrist samples](references/usage-and-environment-samples.md)128- [Speech, face, temperature, ECG/PPG, deletion, and testing](references/speech-face-and-health-samples.md)129- [SensorKit framework](https://sosumi.ai/documentation/sensorkit)130- [SRSensorReader](https://sosumi.ai/documentation/sensorkit/srsensorreader)131- [SRSensor](https://sosumi.ai/documentation/sensorkit/srsensor)132- [SRDevice](https://sosumi.ai/documentation/sensorkit/srdevice)133- [SRFetchRequest](https://sosumi.ai/documentation/sensorkit/srfetchrequest)134- [Configuring your project for sensor reading](https://sosumi.ai/documentation/sensorkit/configuring-your-project-for-sensor-reading)135- [com.apple.developer.sensorkit.reader.allow](https://sosumi.ai/documentation/bundleresources/entitlements/com.apple.developer.sensorkit.reader.allow)