Commissioning API unter Android

Mit der Commissioning API kann eine App die Inbetriebnahme für Folgendes auslösen:

  • Ihr Fabric und das Google-Fabric
  • Nur das Google-Fabric

Möglichkeiten zur Inbetriebnahme von Matter-Geräten

Der Inbetriebnahmevorgang kann auf folgende Arten gestartet werden:

Inbetriebnahme direkt in Ihrer App anfordern

Die Inbetriebnahme kann direkt in der App über eine Schaltfläche ausgelöst werden. Es gibt zwei Möglichkeiten:

Für einzelne Fabrics

So fordern Sie die Inbetriebnahme an:

  1. Initialisieren Sie einen ActivityResultLauncher in Ihrer Aktivität. Wenn der Nutzer das Gerät im Google-Fabric in Betrieb genommen hat, kann das Ergebnis den Namen enthalten, den der Nutzer dem Gerät bei der Inbetriebnahme zugewiesen hat.

    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. Erstellen Sie eine CommissioningRequest, einschließlich der empfangenen Nutzlastdaten, und legen Sie die Option fest, das Gerät im Google-Fabric in Betrieb zu nehmen. Verwenden Sie dazu setStoreToGoogleFabric:

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

    Wenn Sie das Gerät sowohl im Google-Fabric als auch in Ihrem eigenen Fabric in Betrieb nehmen möchten, legen Sie Ihren Inbetriebnahmeservice mit setCommissioningService in der CommissioningRequest fest.

  3. Verwenden Sie die CommissioningClient Instanz, um die Inbetriebnahme zu starten:

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

    Dabei ist _commissioningIntentSender so definiert:

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

  4. Sobald CommissioningClient den Intent-Absender zurückgibt, starten Sie ihn:

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

Für mehrere Fabrics (Multi-Admin)

Wenn Sie mehrere Matter Fabrics auf einem Gerät einrichten müssen, lesen Sie den Hilfeartikel Multi-Admin für die Commissioning API unter Android.

Einstiegspunkt für die Matter-Inbetriebnahme für Schnelles Pairing oder QR-Code-Scanning (nur unter Android)

Die Inbetriebnahme kann unter Android auf zwei Arten über Schnelles Pairing oder einen QR-Code angefordert werden:

Für einzelne Fabrics

Mit dem ACTION_START_COMMISSIONING Intent-Filter können Sie die vollständige Inbetriebnahme für eine App ermöglichen, ohne dass die GHA erforderlich ist. Bei der Inbetriebnahme im Google-Fabric kann der Nutzer dem Gerät einen Namen zuweisen.

Ablauf der Inbetriebnahme mit ACTION_START_COMMISSIONING
Abbildung 1: Inbetriebnahmevorgang mit ACTION_START_COMMISSIONING

Wenn Sie die Inbetriebnahme im Google-Fabric unterstützen möchten, fügen Sie der ausgewählten Aktivitätsdeklaration in der Datei AndroidManifest.xml den folgenden intent-filter hinzu:

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

Der intent-filter wird verwendet, um Ihre App in die Liste der vorgeschlagenen Matter Apps in der App-Auswahl der Commissioning APIs aufzunehmen. Wenn Ihre App nicht zu den vorgeschlagenen Apps gehört, wird sie in der Option Andere App auswählen angezeigt.

Sobald der Nutzer Ihre App auswählt, wird sie gestartet und mit einem ACTION_START_COMMISSIONING Intent zur ausgewählten Aktivität weitergeleitet.

Für mehrere Fabrics (Multi-Admin)

Sie können den FastPair-Vorgang auch in Multi-Admin-Szenarien verwenden. Weitere Informationen finden Sie im Hilfeartikel Multi-Admin für die Commissioning API unter Android.

Eingehenden Intent verarbeiten

Sobald Ihre Aktivität gestartet wurde, sollte sie nach dem vorhandenen ACTION_START_COMMISSIONING-Intent suchen und die Nutzlast abrufen:

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)
}

Ein Nutzlastwert, der nicht null ist, bedeutet, dass der Nutzer bereits den QR-Code des Geräts gescannt oder den Kopplungsschlüssel eingegeben hat. Ein null-Nutzlastwert bedeutet nicht , dass die Inbetriebnahme abgebrochen werden sollte.

Benachrichtigungen zur Erkennung von Geräten, die in Betrieb genommen werden können, unterdrücken

Beispiel für eine Halbsheet-Benachrichtigung unter Android
Abbildung 1: Beispiel für eine Android-Halbsheet-Benachrichtigung

Standardmäßig verwenden Google Play services unter Android Halbsheet-Benachrichtigungen, die die untere Hälfte des Bildschirms eines Mobilgeräts abdecken, um Nutzer proaktiv darauf hinzuweisen, dass sich in der Nähe Matter Geräte befinden, die in Betrieb genommen werden können.

Um Unterbrechungen zu vermeiden, während Ihre App im Vordergrund ausgeführt wird, können Sie diese Benachrichtigungen unterdrücken, indem Sie die suppressHalfSheetNotification() Methode aufrufen. Weitere Informationen finden Sie in der API-Dokumentation.

Die durch diese API aktivierte Unterdrückung läuft ab, wenn Ihre App länger als 15 Minuten im Vordergrund ausgeführt wird. Wenn Sie die Unterdrückung nach einem Timeout wieder aktivieren möchten, rufen Sie suppressHalfSheetNotification() noch einmal auf. Andernfalls werden Halbsheet-Benachrichtigungen angezeigt.

Wie sollten Sie Matter-Geräte in Ihrem Fabric für Google freigeben?

Google empfiehlt dringend, die Commissioning API als primäre Methode zu verwenden, um ein Gerät, das Sie bereits in Ihrem eigenen Fabric eingerichtet haben, für das Google-Fabric freizugeben. Die Share API hat ihre Einschränkungen und sollte für andere Anwendungsfälle reserviert werden.

Warum sollten Sie die Commissioning API anstelle der Share API verwenden?

Mit der Commissioning API können Sie die Freigabe eines Geräts direkt für das Google-Fabric auslösen. Dies ist die bevorzugte Methode, wenn sie möglich ist. Bei der Share API sind mehr Schritte für den Endnutzer erforderlich. Der Endnutzer muss beispielsweise GHA installiert haben und während des Vorgangs GHA auswählen, damit die Freigabe erfolgreich ist.

Wenn Sie die Commissioning API verwenden möchten, öffnen Sie das Inbetriebnahmefenster und rufen Sie die Commissioning API auf, wie unter Commissioning API als sekundärer Matter-Inbetriebnehmer verwenden beschrieben.

Wann sollten Sie die Share API verwenden?

Mit der Share API können Sie dem Endnutzer die Möglichkeit geben, eine geeignete Anwendung auszuwählen, um ein Gerät allgemein für andere Matter Ökosysteme freizugeben.