Sensorkit

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
• Entitlements
• Info.plist Configuration
• Authorization
• Available Sensors
• SRSensorReader
• Recording and Fetching Data
• SRDevice
• Common Mistakes
• Review Checklist
• 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.
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.

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

The reader communicates through SRSensorReaderDelegate. Load the Delegate Method Catalog when wiring the complete authorization, recording, device-fetch, and sample-fetch lifecycle.

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