# Intent-based Commissioning for Matter

While the Matter SDK provides a `Task`-based API to start Matter commissioning
with varying parameters, observing the result, and optionally adding
credentials, there are situations where an entry point of only a QR code is
needed. For example, from a generalized camera application that wishes to
provide a shortcut to start commissioning when a QR code is seen in the
viewfinder.

Before continuing, make sure all
[Prerequisites](https://developers.home.google.com/matter/get-started) have been met.

## Matter QR codes

Matter QR codes take the general form of
`MT:Y3.13OTB00KA0648G00`, where the `MT:` prefix is a constant, and the suffix
is a base 38-encoded string using the alphabet `[A-Z0-9.-]`. The suffix must
always be at least 19 characters, but may be longer as well.

Determining whether a QR code represents a Matter QR code can be done with the
following regex in Java:

```kotlin
fun isMatterQrCode(value: String): Boolean {
  return value.matches(Regex("""MT:[A-Z0-9.-]{19,}"""))
}
```

For example, the following QR code represents `MT:Y3.13OTB00KA0648G00`:

![Matter QR code example](https://developers.home.google.com/static/samples/intent-based-commissioning/images/example-matter-qr-code.png)

## Intent Format

This QR code format may be used as a URI to start the commissioning flow by
sending an `Intent` with `ACTION_VIEW`, the URI specified in the `data`, and the
target package set to Google Play Services:

    fun startCommissioning(context: Context, qrCodeString: String): Boolean {
      val intent =
        Intent(Intent.ACTION_VIEW)
          .setData(Uri.parse(qrCodeString))
          .setPackage("com.google.android.gms")

      try {
        context.startActivity(intent)
        return true
      } catch (ex: ActivityNotFoundException) {
        // Supporting Play Services version not available.
        return false
      }
    }

## Sample app

This sample app shows how to start commissioning a Matter device when a
Matter-compliant QR code is seen in the viewfinder of the camera.

[Download
the Intent-based Commissioning sample app](https://developers.home.google.com/static/samples/intent-based-commissioning/matteribc.zip)

The code in this sample app leverages the following Android libraries:

- [CameraX](https://developer.android.com/training/camerax)
- [Barcode Scanning](https://developers.google.com/ml-kit/vision/barcode-scanning)

The following documents are also useful to understand the code written for this
sample app:

- [Getting Started with
  CameraX](https://developer.android.com/codelabs/camerax-getting-started#0)
- [Scan Barcodes with ML Kit on Android](https://developers.google.com/ml-kit/vision/barcode-scanning/android)

### Usage

When the app starts, the camera preview is shown on the screen. When a QR code
for a Matter device is detected, a dialog is shown to confirm whether
commissioning for that Matter device should be performed:

![camera preview 1](https://developers.home.google.com/static/samples/intent-based-commissioning/images/camera-preview-1.png)
![camera preview 2](https://developers.home.google.com/static/samples/intent-based-commissioning/images/camera-preview-2.png)

If commissioning is confirmed, then the "App Picker" supported by the
Google Home Mobile SDK is launched.

The App Picker initially shows a set of default commissioning applications (for example, the Google Home app as shown on the first screenshot). If one taps on "Choose other app", then other applications that support the Google Home Mobile SDK commissioning flow are shown (see the second screenshot).

![Choose an app - GHA](https://developers.home.google.com/static/samples/intent-based-commissioning/images/apppicker_gha.png)
![Choose an app - Other apps](https://developers.home.google.com/static/samples/intent-based-commissioning/images/apppicker_otherapps.png)

The selected application is then launched to perform the commissioning of the device.