Troubleshooting
The setup wizard did not open
Section titled “The setup wizard did not open”Open it manually:
- Unity: Window > HealthBridge > Setup Wizard.
- Unreal Engine: Tools > HealthBridge > Setup Wizard.
In Unity, wait for package import and compilation to finish first. In Unreal, confirm the plugin is enabled and restart the editor after enabling it.
The editor works, but a device does not
Section titled “The editor works, but a device does not”The editor uses mock data. Verify the mobile prerequisites separately:
- iOS requires a physical device, a HealthKit-capable App ID, matching provisioning, entitlement, and clear usage descriptions.
- Android requires Health Connect and manifest declarations for each requested health permission.
Review iOS and Android platform setup and test the installed build, not only an editor/PIE run.
iOS returns no data after initialization
Section titled “iOS returns no data after initialization”This can be an access decision rather than an initialization error. Apple does not expose per-type read permission state. Handle an empty result in the app and direct the player to iOS Health privacy settings if they need to change access.
Android initialization or permissions fail
Section titled “Android initialization or permissions fail”Confirm that Health Connect is installed and current, then confirm every selected type has the matching manifest permission. Health Connect only shows permissions declared in the final app manifest. Treat denied optional types, such as heart rate, as feature-level failures instead of crashing or blocking the rest of the experience.
No live heart-rate samples arrive
Section titled “No live heart-rate samples arrive”The base SDK does not promise live streaming from a third-party watch app. For live companion sessions, install the separate HealthBridge Real-Time Heart Rate add-on and verify the companion app is present and reachable. On Wear OS, verify the phone and watch apps share package identity and signing.
A route read fails
Section titled “A route read fails”Workout routes are an optional provider extension. Use the workout ID returned by HealthBridge, and handle an unsupported, missing-consent, or unavailable result without failing the workout experience.
Preparing a useful support report
Section titled “Preparing a useful support report”Include the engine and version, SDK/plugin version, target platform and OS version, the operation that failed, and redacted error text. Do not include health records, record IDs, screenshots of health data, credentials, signing files, or raw native callback payloads.