End-user onboarding flows

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?
• Key phases of the sharing flow
• Technical implementation
• 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	Home APIs for 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 partner scenario, and is included in Technical implementation.
Cloud-to-cloud linking	Cloud-to-cloud for account 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	Matter 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.

2. Call the Google Commissioning API 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. This adds the devices to the Google 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.

You produce both Cloud-to-cloud and Matter devices

1. Perform Cloud-to-cloud 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.

3. Call the Google Commissioning API 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.

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

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.

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.

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

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