Capabilities & Permissions

A sensor on watchOS needs three things before it produces data: a capability on the target, a background mode if it runs with the wrist lowered, and a privacy string explaining why.

Everything on this page is set on the CarpWatch Watch App target.

1. Capabilities

Select the watch target → Signing & Capabilities → + Capability and add:

Capability	Needed for
Background Modes → Audio	The microphone background session, and any sound sensing
Background Modes → Workout processing	The workout background session
Background Modes → Location updates	Location sampling
HealthKit (tick Background Delivery)	Heart rate

This writes CarpWatch Watch App.entitlements:

CarpWatch Watch App.entitlements

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>com.apple.developer.healthkit</key>
  <true/>
  <key>com.apple.developer.healthkit.background-delivery</key>
  <true/>
</dict>
</plist>

Note

You do not need HealthKit, microphone, or location capabilities on the Runner (iOS) target for this package (unless your phone app also needs them)

2. Background modes

Adding the capabilities above writes the background modes for you. Verify the watch target ends up with:

<key>WKBackgroundModes</key>
<array>
  <string>workout-processing</string>
</array>
<key>UIBackgroundModes</key>
<array>
  <string>audio</string>
  <string>location</string>
</array>

Caution

The background mode has to match the backgroundSessionType you set on the AppleWatchDevice. microphone needs the audio mode; workout needs workout-processing. Without the matching mode the session fails to start and the watch app is suspended as soon as the participant lowers their wrist.

3. Privacy strings

watchOS refuses to show a permission prompt whose purpose string is missing. Xcode 15 and later generate the watch app’s Info.plist from build settings, so the easiest place to add these is the target’s Info tab.

Key	Needed for	Example value
NSHealthShareUsageDescription	Heart rate	“This study reads your heart rate from the Health app for X.”
NSHealthUpdateUsageDescription	Required alongside the above	“This study does not write any data to the Health app.”
NSMicrophoneUsageDescription	Sound sensing and the microphone background session	“The microphone is used to measure the noise level around you. No audio is recorded or saved.”
NSLocationWhenInUseUsageDescription	Location	“Your location is collected to describe where you spend your time.”
NSLocationAlwaysAndWhenInUseUsageDescription	Location in the background	Same as above
NSBluetoothAlwaysUsageDescription	Bluetooth scanning	“Nearby Bluetooth devices are scanned to estimate social context. No connection is made.”

Next step

The watch app