Set up HealthKit on iOS

Real HealthKit behavior requires a physical iOS device and an app identity whose signing profile includes HealthKit.

Configure Apple capabilities

1. Open the Apple Developer identifier used by the Unreal project.
2. Enable the HealthKit capability for that App ID.
3. Regenerate or refresh the development and distribution profiles that use the identifier.
4. Configure the matching team and provisioning profile in Unreal’s iOS settings or your signing pipeline.
5. Verify that the signed application contains com.apple.developer.healthkit = true.

The plugin cannot make an App ID HealthKit-capable on your behalf. Signing and provisioning must agree with the final application identifier.

Configure usage descriptions

Under Project Settings > Plugins > HealthBridge, replace fallback text with product-specific explanations for:

• Health data the app reads.
• Health data the app writes.

Explain the user-visible feature and requested category. Do not ship generic SDK placeholder text.

Select HealthBridge permissions

Open Tools > HealthBridge > Permissions and enable only the read and write types required by the product. Read and write access are separate.

The plugin maps the selected unified IDs to HealthKit types. A registry entry does not guarantee a typed public API, so confirm public API status before building a feature around it.

Understand iOS authorization

Apple does not reveal every per-type read decision:

• Initialization can succeed after the authorization sheet closes even if the player declined a read type.
• A denied read can look like a successful empty result.
• Write denial can fail without a detailed per-type disclosure.

Use an empty state that does not claim the player has no records or granted access. Provide instructions for reviewing Health access in iOS Settings or the Health app.

Package and verify

1. Package the project for a physical iOS device.
2. Inspect the signed app’s entitlements.
3. Confirm the app contains product-specific HealthKit usage descriptions.
4. Install the exact packaged artifact on a device.
5. Trigger authorization from a clear in-game explanation.
6. Test allowed, denied, empty, and partial data scenarios.

The editor mock and iOS simulator do not prove real HealthKit behavior.

Common failures

• Authorization UI never appears: verify requested types and initialization.
• App exits when requesting HealthKit: verify usage descriptions.
• Signing fails: refresh profiles after enabling HealthKit on the App ID.
• Reads are empty: test with known device data and remember that iOS can hide read denial.

See device validation and troubleshooting.