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.

Your user experience (UX) should adhere to three guiding principles:

1. **Consistency**: Ensure that flows are aligned throughout the integration process.
2. **Transparency**: Be up front in explaining how Health Connect works alongside your app.
3. **Clarity**: Help users access Health Connect through your app.

At a high-level, the UX flow can be broken down into the following stages:

![Health Connect UX flow](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/hc_ux_flow_stages.png)

## Promote Health Connect

Showcasing Health Connect in your app depends on the UX patterns and
conventions established in your UI.

### Focus on the user benefit

The first time you introduce Health Connect to users, aim to offer
a meaningful reason for them to make use of your integration.

Rather than describing Health Connect's features, tailor your
message to how a user benefits from those features.

![Health Connect user benefits](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/hc_user_benefits.png)

### Use clear language

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.

Your UX should help users form an idea of how Health Connect interacts with
your app, so it's important to consider which button labels work best toward
achieving that goal.

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

![Health Connect clear language](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/hc_use_clear_language.png)

### Promote Health Connect

Here are a few ways you can promote Health Connect in your app:

- As part of your [app's setup flow](https://developer.android.com/health-and-fitness/guides/health-connect/design/ui-guidelines#app-setup-flow)
- With a [card](https://developer.android.com/health-and-fitness/guides/health-connect/design/ui-guidelines#card) in your app's home screen
- Through an entrypoint within a [Settings](https://developer.android.com/health-and-fitness/guides/health-connect/design/ui-guidelines#settings) screen
- With an [Android 13 APK download](https://developer.android.com/health-and-fitness/guides/health-connect/design/ui-guidelines#android-13-download) button for Android 13 versions and lower
- When promoting [new data types](https://developer.android.com/health-and-fitness/guides/health-connect/design/ui-guidelines#new-data-types)
- With a modal or dialog when updating the app, similar to the app's setup flow

#### App setup and requesting permissions flow

![App setup and request permissions](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/hc_app_setup_request_permissions.png)

#### Home Screen Promo Card Flow

![Home screen promo flow](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/hc_home_screen_promo.png)

#### Settings

![Settings with entry point](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/hc_settings.png)

#### Android 13 APK Download

![Android 13 APK download](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/hc_android_13_apk.png)

### Onboard new data type(s) and requesting permissions

Apps that already have a Health Connect integration can request new data types
in addition to the already granted ones.

Only the new data type(s) requested should be shown in the permissions screen,
to avoid confusing users.

The following are a few examples of how to promote new data types(s):

- [Reuse existing conventions](https://developer.android.com/health-and-fitness/guides/health-connect/design/ui-guidelines#reuse)
- [Emphasize the value proposition](https://developer.android.com/health-and-fitness/guides/health-connect/design/ui-guidelines#value)
- [Contextualize permissions](https://developer.android.com/health-and-fitness/guides/health-connect/design/ui-guidelines#contextualize)

#### Reuse existing conventions

If your app already promotes new data in other ecosystems, we recommend doing
the same for Health Connect in Android, and adapt the language where relevant.

#### Emphasize the value proposition

Why would users want to use this data in your app?

- Examples: reading the data
  - Gives users more accurate insights in your app
  - Users can see all data in one place in your app
- Example: writing the data
  - Users can share this new data from your app with other compatible health and fitness apps on their phone

#### Contextualize permissions

Ask for new permissions where it makes sense for users, so they know what's
being asked of them.

Examples:

- 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.
- If you have a dedicated section in your app, for example **Sleep**, promote the corresponding permission there.

![Requesting new data type](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/hc_requesting_new_data_type.png)

## Data access and synchronization

Your app's Settings screen should provide users with options to manage their
connection to Health Connect. This gives users control over data
synchronization and access to their data.

![Revoked and cancelled permissions](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/hc_revoked_cancelled_permissions.png)

### Sync with Health Connect

This toggle provides a way for users to pause or resume data
synchronization between your app and Health Connect.

- **When toggled on:** Your app actively reads and writes to Health Connect, as per the permissions granted by the user.
- **When toggled off:** Your app should stop all data synchronization with Health Connect. If you programmatically revoke permissions using [`revokeAllPermissions()`](https://developer.android.com/reference/kotlin/androidx/health/connect/client/PermissionController#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.

### Manage access

The **Manage access** button should provide a direct link for the user to manage
your app's permissions from within the Health Connect app. This gives the user
full control and transparency.

### Insufficient access

If your app has insufficient Health Connect access, users should be presented
with the following screen across all entry points:

![App with insufficient access](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/hc_insufficient_access.png)

### Permissions cancelled twice

If the user selects **Cancel** on the permissions request screen twice in a
row, your app should present the user with a screen similar to the following:

![Permissions cancelled twice by user](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/hc_permissions_cancelled_twice.png)
| **Note:** Once this screen is displayed, users need to re-enable permissions from within the Health Connect Settings menu.

## Reading \& displaying data

To build trust and assure users that their data is being read correctly,
it's important to show users how your app obtains data, which comes from the
[`packageName` property of the `DataOrigin` class](https://developer.android.com/reference/kotlin/androidx/health/connect/client/records/metadata/DataOrigin#packageName()).

There are two ways to achieve this:

1. [Basic attribution](https://developer.android.com/health-and-fitness/guides/health-connect/design/ui-guidelines#basic)
2. [Attribution with education](https://developer.android.com/health-and-fitness/guides/health-connect/design/ui-guidelines#education)

### Basic attribution

At a minimum, your user interface (UI) should display the app source icon
and name (or only the app name if the icon can't be shown).
Basic attribution is suitable for the following screens: Home,
Activity log, and Activity details.

To support proper attribution, your application can display the name and icon
of the application that originally recorded the data. This improves user trust
and provides clarity about where health information originated.

You don't need to request any sensitive permission, such as
`QUERY_ALL_PACKAGES`, in order to retrieve this information. The following
example demonstrates how to retrieve the app label and icon for a given package
from the `PackageManager`:  

    fun getAppLabelAndIcon(context: Context, packageName: String): Pair<CharSequence?, Drawable?>{
        return try {
          val pm = context.pacageManager
          val appInfo = pm.getApplicationInfo(packageName, 0)
          val label = pm.getApplicationLabel(appInfo)
          val icon = pm.getApplicationIcon(appInfo)
          label to icon
        } catch (e: PackageManager.NameNotFoundException){
          null to null
        }
    }

This utility ensures proper attribution by displaying both the app name
and icon alongside the data.
See the implementation in the [HealthConnectManager.kt sample](https://github.com/android/health-samples/blob/main/health-connect/HealthConnectSample/app/src/main/java/com/example/healthconnectsample/data/HealthConnectManager.kt#L89).

![Basic attribution for reading data](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/hc_basic_attribution.png)

### Attribution with education

Your app should help users obtain information about where data
originates from, with a direct link to the "App permissions" screen in
Health Connect. This type of attribution is suitable for the following screens:
Activity details, Reports and insights.

![](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/hc_education_variation.png)
![](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/hc_education_variation.png)
![](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/hc_education_variation_3.png)
![](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/hc_education_variation_3.png)

### Data Sync

If there's enough latency when syncing your app with Health Connect, we
recommend that your app show this notification while the data is syncing.
This informs the user that something is happening and that it may take
a while to finish. If you use notifications for syncing, they should be set
to a low priority by default.

![Data sync status shown](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/hc_data_sync.png)

## Assets

Product icons should be used on a white or a very light gray background.
You may also use the icon on a black background if necessary.
| **Note:** All product icons should have a transparent background when placed on a solid background.

![Icon guidelines](https://developer.android.com/static/health-and-fitness/guides/health-connect/images/health_connect_logo_guidelines.png)

Download the following icons:

- Health Connect logo

  [Download](https://developer.android.com/static/downloads/assets/health_connect_logo.png)
- Health Connect logo white

  [Download](https://developer.android.com/static/downloads/assets/health_connect_logo_white.png)