Plan for onboarding users

We recommend the following guidance to onboard users onto your app.

Onboard your app

Many apps have a custom onboarding flow such as feature education or asking user consent. Developers are strongly recommended to export an onboarding activity that Health Connect launches when the user interacts with the app for the first time. To do so, add the following in your manifest:

<!-- Required to support pre-Android 14 devices with APK Health Connect -->
<activity
  android:name=".OnboardingActivity"
  android:exported="true"
  android:permission="com.google.android.apps.healthdata.permission.START_ONBOARDING"
  <intent-filter>
    <action android:name="androidx.health.ACTION_SHOW_ONBOARDING"/>
  </intent-filter>
</activity>
<!-- Required to support Android 14+ devices with platform Health Connect -->
<activity-alias
  android:name="UAndAboveOnboardingActivity"
  android:exported="true"
  android:targetActivity=".OnboardingActivity"
  android:permission="android.permission.health.START_ONBOARDING">
  <intent-filter>
    <action android:name="android.health.connect.action.ACTION_SHOW_ONBOARDING" />
  </intent-filter>
</activity-alias>

Please note that support for this feature is not yet available for Android 14 but is coming soon.

When a user attempts to connect your app to Health Connect, the exported activity is launched. This activity must do the following:

  • Display any relevant user education such as explaining what data is written or read.
  • Ask the user to grant consent if required.
  • Make a permissions request to Health Connect.
  • Carry out any other application specific logic such as scheduling a periodic worker.
  • Once complete, allow the user to dismiss the activity.

For apps that don't export an onboarding activity, Health Connect instead brings the user to the Manage permissions screen once the user attempts to connect the app. This may be acceptable for apps where permissions being granted is the only prerequisite for the integration to function.

Note that the onboarding activity may be launched more than once, for example if the user later revokes permissions to your app and then reconnects it.