This guide provides UX guidance for designing seamless Google Home APIs
device permissions and sharing for the onboarding experience in your
application.

The main topics described here are:

- [Why share devices with Google Home?](https://developers.home.google.com/apis/android/onboarding-guidance#why_share_devices_with_google_home)
- [Key phases of the sharing flow](https://developers.home.google.com/apis/android/onboarding-guidance#key_phases_of_the_sharing_flow)
- [Technical implementation](https://developers.home.google.com/apis/android/onboarding-guidance#implementation)
- [UX best practices](https://developers.home.google.com/apis/android/onboarding-guidance#ux_best_practices)

## Why share devices with Google Home?

To enjoy the capabilities that Home APIs have to offer, users must share
their devices with Google Home because:

- It's a technical requirement for Google to use these devices in automations.
- It helps maintain a consistent and flexible Google Home experience.
  - Ensuring that devices are presented consistently across Home API-enabled apps is critical to avoid creating a fragmented and confusing user experience where users must jump between apps to accomplish basic tasks.

## Key components of the sharing flow

| Component | Program | Description |
|---|---|---|
| Permissions API on Android | [Home APIs for Permissions on Android](https://developers.home.google.com/apis/permissions) | Prompts users to grant permissions to your app. Before using any of the Home APIs, your app must have permission to access devices in the user's home (referred to in the API as the **structure** ). The order in which this step is performed, however, depends on the developer scenario, and is included in [Technical implementation.](https://developers.home.google.com/apis/android/commissioning/onboarding-guidance#implementation) |
| Cloud-to-cloud linking | [Cloud-to-cloud for account linking](https://developers.home.google.com/cloud-to-cloud/enhancements/deep-linking) | Lets you start the account-linking process to share cloud-connected devices with Google Home from within your app. To reduce user friction, we recommend using the deep link capability (available in both Android and iOS) that takes users directly to your specific account-linking page in GHA. |
| Commissioning API on Android | [Matter Commissioning](https://developers.home.google.com/apis/android/commissioning) | While generally thought of as an API to commission new Matter devices, you can also use this API to add the Google fabric to Matter devices that have already been commissioned to another fabric. Therefore, this is a useful tool for the onboarding process. |

## Technical implementation

How you build the sharing flows depends on which devices you plan
to share with Google.

For the following scenarios, we recommend following the steps
in the order provided. This helps provide users with a better overall
experience for users.

### You only produce Matter devices

You produce Matter-enabled devices that you want to commission to Google Home.

1. Call the [Permissions API on Android](https://developers.home.google.com/apis/android/permissions).

2. Call the
   [Commissioning API on Android](https://developers.home.google.com/apis/android/commissioning)
   on each Matter device previously commissioned
   to another fabric.

   1. Because Matter sharing must be performed for each device individually, and there are many screens requiring user input, we recommend that you guide the user through this process by:
      - Providing users with a list of Matter devices not being shared with Google.
      - Allowing users to start the device-sharing process (using the Commissioning API) by clicking on devices in that list.
      - Returning to the list of Matter devices, showing task progress and sharing status to the user.

### You only produce devices shared with Google using Cloud-to-cloud APIs

1. Perform [Cloud-to-cloud deep linking](https://developers.home.google.com/cloud-to-cloud/enhancements/deep-linking).
   This adds the devices to the [Google Home Graph](https://developers.home.google.com/cloud-to-cloud/primer/home-graph).

   1. We recommend performing Cloud-to-cloud linking first to avoid potentially confusing situations like the user being presented with a list that contains devices being shared with Google and devices not being shared with Google.
2. Call the [Permissions API on Android](https://developers.home.google.com/apis/android/permissions).

### You produce both Cloud-to-cloud and Matter devices

1. Perform [Cloud-to-cloud deep linking](https://developers.home.google.com/cloud-to-cloud/enhancements/deep-linking).

   1. We recommend performing Cloud-to-cloud linking first to avoid potentially confusing situations like the user being presented with a list that contains devices being shared with Google and devices not being shared with Google.
2. Call the [Permissions API on Android](https://developers.home.google.com/apis/android/permissions).

3. Call the
   [Commissioning API for Android](https://developers.home.google.com/apis/android/commissioning)
   on each Matter device previously commissioned
   to another fabric.

   1. Because Matter sharing must be performed for each device individually, and there are many screens requiring user input, we recommend that you guide the user through this process by:
      - Providing users with a list of Matter devices not being shared with Google.
      - Allowing users to start the device-sharing process (using the Commissioning API) by clicking on devices in that list.
      - Returning to the list of Matter devices, showing task progress and sharing status to the user.

### You have no devices to share with Google

Call the [Permissions API](https://developers.home.google.com/apis/android/permissions).

## UX best practices

This section contains some critical user journeys to consider when developing
an app leveraging the Home APIs.

### Where to introduce device sharing in the app

This is not an exhaustive list, and you may find other opportunities to provide
a timely Google Home pitch and sharing experience for your users.

These are also not mutually exclusive, and there are multiple entry points:

#### From a Settings menu

![Settings menu as entry point](https://developers.home.google.com/static/apis/images/entry-settings.png) Figure 1. Settings menu as entry point

Because users are probably accustomed to setting up connections with their
Google Home ecosystems by means of a settings menu, this method allows them
to continue with this paradigm.

You may want to separate device sharing (Cloud-to-cloud linking and
the Matter Commissioning API) from
app permissioning (the Permissions API). This gives users the ability
to control which steps they complete, and provides an opportunity for you to
display the connection status to the user.

#### When using devices in automations run by Google

From the Automations tab, users could tap an entry point to the sharing flow,
read a value proposition screen that clearly explains the benefits of moving
forward, and then quickly move through the permissions flow.
![Entry point from a Google-driven automation](https://developers.home.google.com/static/apis/images/entry-automation.png) Figure 2. Entry point from a Google-driven automation

![](https://developers.home.google.com/static/apis/images/entry-automation.png)

#### From commissioning only

This scenario would be primarily for partners that produce Matter devices only
(no Cloud-to-cloud devices) and don't have their own
Matter fabric. The entry
point for the user can come right after an out-of-box-type screen where the
sharing of Matter devices
(via the Commissioning API) and the
app permissioning (via the Permissions API) are part of the same
user experience flow.
![Entry point from Commissioning only](https://developers.home.google.com/static/apis/images/entry-commissioning.png) Figure 3. Entry point from Commissioning only

![](https://developers.home.google.com/static/apis/images/entry-commissioning.png)

### Sharing logic

Some suggestions about user prompts are:

- You should generally prompt users to only complete the missing steps required
  to onboard the platform. For example, long-time customers may already be
  sharing an OEM's devices with Google, in which case they need to only go
  through the Home APIs permissions-granting process to give the app access
  to their Google Home.

- Multiple Google Home administrators may be sharing a Google Home structure,
  and in some cases only one account might be used to share devices with Google.
  As a result, completing Cloud-to-cloud linking shouldn't be
  a prerequisite for prompting for Home APIs permissions.

### Visual design suggestions

![Ideas about the visual design](https://developers.home.google.com/static/apis/images/visual-design.png) Figure 4. Ideas about the visual design

- A clear benefit of onboarding to Google Home (for example, "Create advanced
  automations powered by Google Home" or "Control devices using
  apps of your choice").

- A call-to-action (for example, "Get Started") and a way to cancel
  if the user does not want to continue.

- If space allows, an explanation of what will happen as the user progresses
  through the screens.

- For Matter specifically, when the user has previously
  granted your access to their home through the Home APIs, you can make it
  possible to share the devices in their home with Google Home when
  commissioning new ones.
  For example, you can add a Matter
  device to your fabric and then prompt the user to add this device
  to the Google fabric.

### Content suggestions

It's easier for users to trust something they understand and adds value.
Empower users by providing information to make informed decisions,
including tradeoffs.

#### The critical pitch

Users won't continue down the path of sharing devices if there is not a
strong value proposition to do so.

- Pay special attention to how you position the offering.
- Make it enticing but don't over-promise.
- If the user needs a device that's mentioned in your pitch, make sure that is clearly stated so that they don't hit an unexpected obstacle.
- You may only have one opportunity to capture these users, so make it count.

#### Best practices

1. Start with the user's point of view - the "what's in it for me?" approach.
2. Don't write more than four lines of content in a section block. More words may lose the user's attention. However, clarity and comprehension can be more important than being concise.
3. Automations are fun! Choose an exciting but helpful example if space allows.
4. Try for a playful voice and tone if it aligns with your overall strategy.
5. Use actionable phrases such as "Get started."