| **Note:** If the Commissioning API on Android is not used, users can still commissionMatterdevices using theGoogle Home app (GHA). See[Set up and manageMatter-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 multipleMatterfabrics 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 theGHA. 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 ownMatterfabric, 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 suggestedMatterapps 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 servicesonAndroiduses "halfsheet" notifications that cover the bottom half of a mobile device's screen to provide users with a proactive indication that commissionableMatterdevices 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 haveGHAinstalled, and they must know to selectGHAduring 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 otherMatterecosystems.