| **Note:** If the Commissioning API on Android is not used, users can still commission Matter devices using the Google Home app (GHA). See [Set up and manage Matter-enabled devices in the
| Google Home app](https://support.google.com/googlenest/answer/13127223) for more details.

The Commissioning API allows an app to commission to either:

- Your fabric and the Google fabric.
- Only the Google fabric.

## Ways to commission Matter devices

The commissioning process can be initiated:

- [Directly in your app](https://developers.home.google.com/apis/android/commissioning#request)
- [Through Fast Pair on Android](https://developers.home.google.com/apis/android/commissioning#fast_pair).

### Request commissioning directly in your app

Requesting commissioning directly in the app can be triggered by a button in the
app, and can be done in two ways:

- [For single fabrics](https://developers.home.google.com/apis/android/commissioning#single_fabrics)
- [For multiple fabrics](https://developers.home.google.com/apis/android/commissioning#multiple_fabrics)

#### For single fabrics

To request commissioning:

1. Initialize an `ActivityResultLauncher` in your activity. If the user
   commissioned the device on the Google fabric, the result may include the
   name the user assigned to the device when they commissioned it.

       private val commissioningLauncher =
         registerForActivityResult(StartIntentSenderForResult()) { result ->
           val resultCode = result.resultCode
           if (resultCode == RESULT_OK) {
               Log.i("CommissioningActivity", "Commissioning success")
         val deviceName =
                 CommissioningResult.fromIntentSenderResult(result.resultCode, result.data).deviceName
             } else {
                 Log.i("CommissioningActivity", "Commissioning failed")
             }
           }

2. Construct a
   [`CommissioningRequest`](https://developers.home.google.com/reference/kotlin/com/google/android/gms/home/matter/commissioning/CommissioningRequest),
   including the received payload data, and set the option to
   commission the device to the Google fabric, using
   `setStoreToGoogleFabric`:

       val commissioningRequest = CommissioningRequest.builder()
               .setOnboardingPayload(payload)
               .setStoreToGoogleFabric(true)
         // set all other options that you care about
               .build()

   | **Warning:** If you don't set the payload received in the intent, the QR code scanner appears again, which creates a poor user experience.

   If you want to commission the device to the Google fabric as well as your own
   fabric, set your commissioning service with
   [`setCommissioningService`](https://developers.home.google.com/reference/kotlin/com/google/android/gms/home/matter/commissioning/CommissioningRequest.Builder#setCommissioningService(android.content.ComponentName))
   in the `CommissioningRequest`.
3. Use the
   [`CommissioningClient`](https://developers.home.google.com/reference/kotlin/com/google/android/gms/home/matter/commissioning/CommissioningClient)
   instance to start commissioning:

       commissioningClient
         .commissionDevice(commissioningRequest)
         .addOnSuccessListener { result ->
           Log.i("CommissioningActivity", "Commissioning success")
       _commissioningIntentSender.postValue(result)
             }
             .addOnFailureListener { error ->
               Log.i("CommissioningActivity", "Commissioning failed")
         }

   Where `_commissioningIntentSender` is defined as:  

       private val _commissioningIntentSender = MutableLiveData<IntentSender?>()
           val commissioningIntentSender: LiveData<IntentSender?>
           get() = _commissioningIntentSender

4. Once the `CommissioningClient` returns the intent sender, launch the sender:

       commissioningIntentSender.observe(this) { sender ->
         if (sender != null) {
           commissioningLauncher.launch(IntentSenderRequest.Builder(sender).build())
         }
       }

#### For multiple fabrics (multi-admin)

If you need to set up multiple Matter fabrics on a device,
refer to
[Multi-admin for Commissioning API on Android](https://developers.home.google.com/apis/android/commissioning/multi-admin).

### Matter commissioning entry point for Fast Pair or QR-code scanning (Android only)

Requesting commissioning by means of fast pair or QR code on Android can be
done in two ways:

- [For single fabrics](https://developers.home.google.com/apis/android/commissioning#single_fabrics_qr)
- [For multiple fabrics](https://developers.home.google.com/apis/android/commissioning#multiple_fabrics_qr)

#### For single fabrics

Use the [`ACTION_START_COMMISSIONING`](https://developers.home.google.com/reference/kotlin/com/google/android/gms/home/matter/Matter#ACTION_START_COMMISSIONING()) intent filter
to provide full commissioning capability for an app without needing
the GHA. When commissioning to the Google fabric, this
includes allowing the user to assign a name to the device.
![Commissioning Flow Using ACTION_START_COMMISSIONING](https://developers.home.google.com/static/apis/images/action-start-commissioning-flow.png) **Figure 1** : Commissioning Flow Using `ACTION_START_COMMISSIONING` **Note:** If you are not operating your own Matter fabric, if user permissions for accessing user structures and devices have not been granted prior to commissioning with this API, the device won't be accessible in the app. You must [request permission from the
| user](https://developers.home.google.com/apis/initialization#request_permissions) following the commissioning process, if needed.

To indicate support for Google fabric commissioning, add the following
`intent-filter` to the chosen activity declaration within your
`AndroidManifest.xml` file:  

    <intent-filter>
      <action android:name="com.google.android.gms.home.matter.ACTION_START_COMMISSIONING" />
      <category android:name="android.intent.category.DEFAULT" />
     </intent-filter>

| **Important:** You should only add the `intent-filter` to **one** activity connected to your app, otherwise the behavior is undefined.

The `intent-filter` is used to include your app in the list of suggested
Matter apps in the Commissioning APIs [app
picker](https://developers.home.google.com/apis/android/ux/commissioning#app_picker).
If your app is not one of the suggested apps, it appears in the **Choose other
app** option.

Once the user selects your app, your app is launched and directed to the chosen
activity with an
[`ACTION_START_COMMISSIONING`](https://developers.home.google.com/reference/kotlin/com/google/android/gms/home/matter/Matter#ACTION_START_COMMISSIONING())
intent.

#### For multiple fabrics (multi-admin)

You can also use the FastPair flow in multi-admin scenarios.
For more information, refer to
[Multi-admin for Commissioning API on Android](https://developers.home.google.com/apis/android/commissioning/multi-admin).

## Handle the incoming intent

Once your activity is launched, it should check for the existing
`ACTION_START_COMMISSIONING` intent and retrieve the payload:  

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

    val payload = if (Matter.ACTION_START_COMMISSIONING.equals(intent.getAction())) {
          intent.getStringExtra(Matter.EXTRA_ONBOARDING_PAYLOAD)
        } else {
          null
        }
    CommissioningRequest.builder()
              .setOnboardingPayload(payload)
              .setStoreToGoogleFabric(true)
        // set all other options that you care about
    startCommissioning(commissioningRequest)
    }

A payload value that is not `null` indicates that the user has already either
scanned the device QR code, or entered the pairing key. A `null` payload value
does **not** mean that the commissioning should be aborted.

## Suppress commissionable discovery notifications

![Example of an Android halfsheet notification](https://developers.home.google.com/static/matter/apis/images/android-halfsheet-notification.png) *Figure 1: Example of an Android halfsheet notification*

By default, Google Play services on Android uses
"halfsheet" notifications that cover the bottom half of a mobile device's
screen to provide users with a proactive indication that commissionable
Matter devices are nearby.

To prevent interruptions while your app is in the foreground, you may
suppress these notifications by calling the
[`suppressHalfSheetNotification()`](https://developers.home.google.com/reference/kotlin/com/google/android/gms/home/matter/commissioning/CommissioningClient#suppressHalfSheetNotification())
method. See the API documentation for more information.

The suppression enabled by this API times out if your app is in the foreground
for more than 15 minutes. To re-enable suppression after a timeout, call
`suppressHalfSheetNotification()` again, otherwise halfsheet notifications will
start to appear.

## How should you share Matter devices on your fabric with Google?

Google strongly recommends that you use the Commissioning API as your primary
means of sharing a device that you have already set up on your own fabric with
the Google fabric. The Share API has its limitations and should be reserved for
other use-cases.

### Why should you use the Commissioning API instead of the Share API?

The Commissioning API lets you trigger sharing a device directly with
the Google fabric, which is the preferred method when viable. With the Share
API, more steps are required for the end user. For example, the end user must
have GHA installed, and they must know to select
GHA during the process to ensure success.

To use the Commissioning API, you should open the commissioning window and call
the Commissioning API, as described in
[How to use the Commissioning API as the secondary Matter commissioner](https://developers.home.google.com/apis/android/commissioning/multi-admin#secondary).

### When should you use the Share API?

You can use the
[Share API](https://developers.home.google.com/reference/kotlin/com/google/android/gms/home/matter/commissioning/ShareDeviceRequest)
to let the end-user pick an eligible application to share a device generically
with other Matter ecosystems.