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 standard accelerometer/gyroscope needs.

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:

• Apple-approved research study -- submit a proposal at

researchandcare.org.

• SensorKit entitlement -- Apple grants com.apple.developer.sensorkit.reader.allow

only for approved studies.

• Manual provisioning profile -- Xcode requires an explicit App ID with the

SensorKit capability enabled.

• User authorization -- the system presents a Research Sensor & Usage Data

sheet that users approve per-sensor.

• 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 your study uses:

<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>

</array>

Xcode build settings for manual signing:

Setting

Value

Code Signing Entitlements

YourApp.entitlements

Code Signing Identity

Apple Developer

Code Signing Style

Manual

Provisioning Profile

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.

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)")

    }

}

Check a reader's current status before recording:

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:

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

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

CMAccelerometerData

.rotationRate

Rotation rate

CMGyroData

.pedometerData

Step/distance data

CMPedometerData

.visits

Visited locations

SRVisit

.mediaEvents

Media interactions

SRMediaEvent

.faceMetrics

Face expressions

SRFaceMetrics

.heartRate

Heart rate

Heart rate data

.odometer

Speed/slope

Odometer data

.siriSpeechMetrics

Siri speech

SRSpeechMetrics

.telephonySpeechMetrics

Phone speech

SRSpeechMetrics

.wristTemperature

Wrist temp (sleep)

SRWristTemperatureSession

.photoplethysmogram

PPG stream

SRPhotoplethysmogramSample

.electrocardiogram

ECG stream

SRElectrocardiogramSample

Environment Sensors

Sensor

Type

Sample Type

.ambientLightSensor

Ambient light

SRAmbientLightSample

.ambientPressure

Pressure/temp

Pressure data

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

keyboardReader.delegate = self

The reader communicates entirely through SRSensorReaderDelegate:

Delegate Method

Purpose

sensorReader(_:didChange:)

Authorization status changed

sensorReaderWillStartRecording(_:)

Recording is about to start

sensorReader(_:startRecordingFailedWithError:)

Recording failed to start

sensorReaderDidStopRecording(_:)

Recording stopped

sensorReader(_:didFetch:)

Devices fetched

sensorReader(_:fetching:didFetchResult:)

Sample received

sensorReader(_:didCompleteFetch:)

Fetch completed

sensorReader(_:fetching:failedWithError:)

Fetch failed

Recording and Fetching Data

Start and Stop Recording

// Begin recording -- sensor stays active as long as any app has a stake

reader.startRecording()

// Stop recording -- framework deactivates the sensor when

// no app or system process is using it

reader.stopRecording()

Fetch Data

Build an SRFetchRequest with a time range and target device, then pass it to

the reader:

let request = SRFetchRequest()

request.device = SRDevice.current

request.from = SRAbsoluteTime(CFAbsoluteTimeGetCurrent() - 86400 * 2)  // 2 days ago

request.to = SRAbsoluteTime.current()

reader.fetch(request)

Receive results through the delegate:

func sensorReader(

    _ reader: SRSensorReader,

    fetching request: SRFetchRequest,

    didFetchResult result: SRFetchResult<AnyObject>

) -> Bool {

    let timestamp = result.timestamp

    switch reader.sensor {

    case .ambientLightSensor:

        if let sample = result.sample as? SRAmbientLightSample {

            let lux = sample.lux

            let chromaticity = sample.chromaticity

            let placement = sample.placement

            processSample(lux: lux, chromaticity: chromaticity, at: timestamp)

        }

    case .keyboardMetrics:

        if let sample = result.sample as? SRKeyboardMetrics {

            let words = sample.totalWords

            let speed = sample.typingSpeed

            processKeyboard(words: words, speed: speed, at: timestamp)

        }

    case .deviceUsageReport:

        if let sample = result.sample as? SRDeviceUsageReport {

            let wakes = sample.totalScreenWakes

            let unlocks = sample.totalUnlocks

            processUsage(wakes: wakes, unlocks: unlocks, at: timestamp)

        }

    default:

        break

    }

    return true  // Return true to continue receiving results

}

func sensorReader(_ reader: SRSensorReader, didCompleteFetch request: SRFetchRequest) {

    print("Fetch complete for \(reader.sensor)")

}

func sensorReader(

    _ reader: SRSensorReader,

    fetching request: SRFetchRequest,

    failedWithError error: any Error

) {

    print("Fetch failed: \(error)")

}

Data Holding Period

SensorKit imposes a 24-hour holding period on newly recorded data. Fetch

requests whose time range overlaps this period return no results. Design data

collection workflows around this delay.

SRDevice

SRDevice identifies the hardware source for sensor samples. Use it to

distinguish data from iPhone versus Apple Watch.

// Get the current device

let currentDevice = SRDevice.current

print("Model: \(currentDevice.model)")

print("System: \(currentDevice.systemName) \(currentDevice.systemVersion)")

// Fetch all available devices for a sensor

reader.fetchDevices()

Handle fetched devices through the delegate:

func sensorReader(_ reader: SRSensorReader, didFetch devices: [SRDevice]) {

    for device in devices {

        let request = SRFetchRequest()

        request.device = device

        request.from = SRAbsoluteTime(CFAbsoluteTimeGetCurrent() - 86400)

        request.to = SRAbsoluteTime.current()

        reader.fetch(request)

    }

}

func sensorReader(_ reader: SRSensorReader, fetchDevicesDidFailWithError error: any Error) {

    print("Failed to fetch devices: \(error)")

}

SRDevice Properties

Property

Type

Description

model

String

User-defined device name

name

String

Framework-defined device name

systemName

String

OS name (iOS, watchOS)

systemVersion

String

OS version

productType

String

Hardware identifier

current

SRDevice

Class property for the running device

Common Mistakes

DON'T: Attempt to use SensorKit without the entitlement

// WRONG -- fails at runtime with SRError.invalidEntitlement

let reader = SRSensorReader(sensor: .ambientLightSensor)

reader.startRecording()

// CORRECT -- obtain entitlement from Apple first, configure manual

// provisioning profile, then use SensorKit

DON'T: Expect immediate data access

// WRONG -- fetching data recorded moments ago returns nothing

reader.startRecording()

// ... record for a few minutes ...

let request = SRFetchRequest()

request.from = SRAbsoluteTime(CFAbsoluteTimeGetCurrent() - 300)

request.to = SRAbsoluteTime.current()

reader.fetch(request)  // Empty results due to 24-hour hold

// CORRECT -- fetch data that is at least 24 hours old

request.from = SRAbsoluteTime(CFAbsoluteTimeGetCurrent() - 86400 * 3)

request.to = SRAbsoluteTime(CFAbsoluteTimeGetCurrent() - 86400)

reader.fetch(request)

DON'T: Forget to set the delegate before fetching

// WRONG -- no delegate means no callbacks, results are silently lost

let reader = SRSensorReader(sensor: .accelerometer)

reader.startRecording()

reader.fetch(request)

// CORRECT -- assign delegate first

reader.delegate = self

reader.startRecording()

reader.fetch(request)

DON'T: Skip per-sensor Info.plist usage detail

// WRONG -- missing NSSensorKitUsageDetail for the sensor

// Authorization sheet shows no explanation, user is less likely to approve

// CORRECT -- add usage detail for every sensor you request

// See Info.plist Configuration section above

DON'T: Ignore SRError codes

// WRONG -- generic error handling

func sensorReader(_ reader: SRSensorReader, fetching: SRFetchRequest, failedWithError error: any Error) {

    print("Error")

}

// CORRECT -- handle specific error codes

func sensorReader(_ reader: SRSensorReader, fetching: SRFetchRequest, failedWithError error: any Error) {

    if let srError = error as? SRError {

        switch srError.code {

        case .invalidEntitlement:

            // Entitlement missing or sensor not in entitlement array

            break

        case .noAuthorization:

            // User has not authorized this sensor

            break

        case .dataInaccessible:

            // Data in 24-hour holding period or otherwise unavailable

            break

        case .fetchRequestInvalid:

            // Invalid time range or device

            break

        case .promptDeclined:

            // User declined the authorization prompt

            break

        @unknown default:

            break

        }

    }

}

Review Checklist

• Apple-approved research study in place before development

• com.apple.developer.sensorkit.reader.allow entitlement lists only needed sensors

• Manual provisioning profile with explicit App ID and SensorKit capability

• NSSensorKitUsageDescription in Info.plist with clear study purpose

• NSSensorKitPrivacyPolicyURL in Info.plist with valid privacy policy URL

• NSSensorKitUsageDetail entries for every requested sensor

• Required key set appropriately for essential vs. optional sensors

• Authorization requested before recording, status checked before fetching

• Delegate assigned before calling startRecording() or fetch(_:)

• Fetch request time ranges account for 24-hour data holding period

• SRError codes handled in all failure delegate methods

• fetchDevices() used to discover available devices before fetching

• stopRecording() called when data collection is complete

• sensorReader(_:fetching:didFetchResult:) returns true to continue or false to stop

References

• Extended patterns (delegate wiring, multi-sensor manager, sample type details): references/sensorkit-patterns.md

• SensorKit framework

• SRSensorReader

• SRSensor

• SRDevice

• SRFetchRequest

• Configuring your project for sensor reading

• com.apple.developer.sensorkit.reader.allow