Health Connect permission UI: Google's guidance for onboarding, requests and settings

Google publishes design guidance for the screens around a Health Connect integration: how to introduce it, when to ask for permissions, what your settings screen should offer, and what to show when the user says no. Much of it is in figures, but the text makes concrete recommendations. This page collects them in Google's words, with the manifest and API pieces each one depends on. The request call itself is on the PermissionController page.

The three principles#

Google's UI overview: "Your app's user interface (UI) should focus on articulating the benefits of using Health Connect, and explain key concepts in a way that enhances user knowledge of what an integration entails." It names three guiding principles:

• "Consistency: Verify that flows are aligned throughout the integration process."
• "Transparency: Be up front in explaining how Health Connect works alongside your app."
• "Clarity: Help users access Health Connect through your app."

On assets, it says product icons "should be used on a white or a very light gray background", with a black background allowed "if necessary".

Introducing Health Connect#

From Google's "Promote Health Connect" page:

• Lead with the benefit. "The first time you introduce Health Connect to users, provide a meaningful reason for them to set it up. Rather than describing Health Connect's features, tailor your message to how a user benefits from those features."
• Label buttons carefully. "Don't ask users to "Connect to Health Connect." This is a jarring sentence and may also confuse a user's understanding of the relationship between apps in the Health Connect ecosystem." Instead: "Try using verb phrases like "set up" or "get started" on your button labels. Or, if you're launching the permissions view, use more specific button text, like "Choose data to share.""
• Promote it in the expected places. Google lists the setup flow, a home-screen card, a Settings entry point, "an Android 13 APK download button for Android 13 versions and lower", promotion of new data types, and "a modal or dialog when updating the app".

Asking for more data types later#

When an existing integration adds types, Google says: "Only the new data type(s) requested should be shown in the permissions screen, to avoid confusing users." In code, that means launching the request with only the new permissions, not your full set:

val granted = healthConnectClient.permissionController.getGrantedPermissions()
val wanted = setOf(
    HealthPermission.getReadPermission(HeartRateRecord::class)   // the newly added type
)
val missing = wanted - granted
if (missing.isNotEmpty()) {
    requestPermissions.launch(missing)   // launcher from createRequestPermissionResultContract()
}

Google's three suggestions for these prompts are to reuse existing conventions, emphasize the value proposition and contextualize permissions. Its examples of context: "Ask for exercise routes permission after users finish a workout in your app.", "If your app implements new permissions, show these together in one promo on the home screen." and "If you have a dedicated section in your app, for example Sleep, promote the corresponding permission there." Route permission has its own consent rules, covered in exercise route consent.

The onboarding activity#

Users can start the connection from Health Connect itself: "Users may initiate the connection to your app directly from the Health Connect app, rather than from within your app." To run your own onboarding in that case, export an activity for androidx.health.ACTION_SHOW_ONBOARDING, protected by com.google.android.apps.healthdata.permission.START_ONBOARDING, plus an activity-alias for android.health.connect.action.SHOW_ONBOARDING protected by android.permission.health.START_ONBOARDING for Android 14 and higher. Google recommends one activity with an alias over two separate activities, which "may lead to increased maintenance complexity."

Google's list of what that activity must do:

• "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."

Without one, "Health Connect instead brings the user to the Manage permissions screen once the user attempts to connect the app", which Google says "may be acceptable for apps where permissions being granted is the only prerequisite for the integration to function." The periodic worker in that list is the background read pattern. Google adds that the Matchmaking API "does not support this trigger".

The privacy policy rationale#

The Health Connect permissions screen links to your privacy policy. Google's get-started guide requires an activity handling androidx.health.ACTION_SHOW_PERMISSIONS_RATIONALE, plus an alias for android.intent.action.VIEW_PERMISSION_USAGE with the android.intent.category.HEALTH_PERMISSIONS category, guarded by android.permission.START_VIEW_PERMISSION_USAGE, for Android 14 and higher. The rule on content: "The activity must display the same privacy policy you provide for your app in the Google Play Console." Play's side of this is covered in Health Connect publishing requirements.

Your settings screen#

Google's "Permissions and data access" page says your settings "should provide users with options to manage their connection to Health Connect", with these elements:

The pages fetched for this article do not name a Jetpack call that opens your app's own permission page. HealthConnectClient offers ACTION_HEALTH_CONNECT_SETTINGS, an "Intent action to open Health Connect settings on this phone", and getHealthConnectManageDataIntent(), an "Intent to open Health Connect data management screen on this phone."

On the off switch, Google warns: "If you programmatically revoke permissions using revokeAllPermissions(), explain to the user that the changes aren't immediately reflected in Health Connect without an app restart. To avoid a confusing user experience, give users the option to go to Health Connect settings to revoke permissions there."

After two cancels, only Settings can fix it#

Google's note on the cancelled-twice screen: "Once this screen is displayed, users need to re-enable permissions from within the Health Connect Settings menu." So after that point, recovery goes through Health Connect settings rather than another request: point the user there, and check getGrantedPermissions() when they return.

Showing where data came from#

Google's data display page asks you to "clearly show how your app obtains data, which comes from the packageName property of the DataOrigin class." At minimum, show "the app source icon and name (or only the app name if the icon can't be shown)" on home, activity log and activity details screens. It adds: "You don't need to request any sensitive permission, such as QUERY_ALL_PACKAGES, in order to retrieve this information." For slow syncs, show a notification, which "should be set to a low priority by default." DataOrigin is covered on the Metadata page.

Pitfalls#

• "Connect to Health Connect" buttons. Google names this label as one to avoid. Use "Set up", "Get started" or "Choose data to share".
• Re-requesting everything on update. Only the new types should appear on the permissions screen. Subtract what getGrantedPermissions() returns.
• Asking without context. Google's examples tie each request to the screen where the data is used, such as routes after a workout.
• Relaunching the request after two cancels. Google says the user must re-enable permissions in Health Connect settings. Build that screen and route the user there.
• An onboarding activity that assumes it runs once. Google: "the onboarding activity may be launched more than once, for example if the user later revokes permissions to your app and then reconnects it." Make it safe to repeat.
• Treating partial grants as failure. Google's guidance across the feature pages is that the app "should still run" and do what it can with what was granted. The permission data types themselves are listed on the Health Connect permissions page.