The Commissioning API supports multi-administration (or multi-admin) for Matter, which means that the Commissioning API can serve as either the primary or secondary Matter commissioner and that you can add your own commissioner:
As the primary Matter commissioner:
- In this mode, the Google fabric is added first, using the Google UX.
- You can add a custom commissioner.
- Your commissioner gets called after the Google fabric is added to the device, then the Matter commissioning window is re-opened.
- If Google cannot complete commissioning to its own fabric first for any reason, your custom commissioning service won't run.
As the secondary Matter commissioner:
- In this mode, you can implement your own commissioning UX and onboard to their own fabric (or to other fabrics).
- The Google Commissioning API can be called later with an open commissioning window to add the Google fabric. In this mode, Google strongly recommends that, when an end-user has granted you permission to use the Home APIs, the app actively prompts users to add Google's fabric (using the Commissioning API) after your commissioning flow has completed.
How to use the Commissioning API as the primary Matter commissioner
These steps show the Google-preferred Matter full-featured, commissioning flow:
The user initiates the commissioning flow in the app. For example, the user taps a button labelled Add Device.
The Google UX takes control and displays the Scan Matter QR Code screen, allowing the user to scan the QR code to begin the setup process.
On the Connect this device to your Google account screen, the user taps I agree to add a device to the Google ecosystem. If the user instead taps Cancel on this screen, all device commissioning ends immediately.
On the Choose a home screen, the user selects the home from which they can control the device. If no home is available, a new home is created. If no appropriate hubs are found in the home, or if the user lacks permissions, the commissioning process ends.
The Device connected screen should appear next, and the Matter setup process begins. The user can choose a room and device name on this screen.
The Getting your device ready screen appears as the device is onboarded to the Matter fabric.
Your app resumes control, and the custom commissioner, if registered, runs now.
How to use the Commissioning API as the secondary Matter commissioner
These steps show the Matter commissioning flow where your commissioning process occurs before the Google commissioning process:
The user initiates the commissioning flow in your app. For example, the user taps Add Device.
Your commissioning UX process is run to add a device to your fabric.
Once completed, you can dictate the ensuing behavior by basing the behavior on your knowledge of the user. For example, if the user has opted into the Google Home APIs, which likely is an indication that the user wants to commission to Google, you could trigger the commissioning process.
Your process calls the Commissioning API and provides the payload, which contains the passcode, discriminator, and other available information.
The Google commissioning process adds the device to the Google fabric.