Commissioning API unter Android

Mit der Commissioning API kann eine App die Inbetriebnahme für Folgendes durchführen:

  • Ihr Stoff und der Google-Stoff.
  • Nur das Google-Stoffarmband.

Matter-Geräte in Betrieb nehmen

Der Inbetriebnahmeprozess kann gestartet werden:

Inbetriebnahme direkt in Ihrer App anfordern

Die Inbetriebnahme kann direkt in der App angefordert werden. Dazu kann eine Schaltfläche in der App verwendet werden. Es gibt zwei Möglichkeiten:

Für einzelne Stoffe

So beantragen Sie die Inbetriebnahme:

  1. Initialisiere ein ActivityResultLauncher in deiner Aktivität. Wenn der Nutzer das Gerät in der Google-Plattform 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. Erstelle ein CommissioningRequest, einschließlich der empfangenen Nutzlastdaten, und lege die Option fest, das Gerät mit setStoreToGoogleFabric in der Google-Umgebung in Betrieb zu nehmen:

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

    Wenn Sie das Gerät sowohl für das Google- als auch für Ihr eigenes Fabric in Betrieb nehmen möchten, legen Sie Ihren Inbetriebnahmedienst mit setCommissioningService im 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 den Absender:

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

Für mehrere Stoffe (mehrere Administratoren)

Wenn Sie mehrere Matter-Stoffe auf einem Gerät einrichten müssen, lesen Sie den Artikel Multi-Admin for Commissioning API on Android.

Matter-Inbetriebnahme-Einstiegspunkt für schnelles Pairing oder QR‑Code-Scanning (nur Android)

Die Inbetriebnahme per „Schnelles Pairing“ oder QR-Code unter Android kann auf zwei Arten erfolgen:

Für einzelne Stoffe

Verwenden Sie den Intent-Filter ACTION_START_COMMISSIONING, um die vollständige Inbetriebnahme einer App zu ermöglichen, ohne dass die GHA erforderlich ist. Bei der Inbetriebnahme in der Google-Infrastruktur kann der Nutzer dem Gerät einen Namen zuweisen.

Ablauf der Inbetriebnahme mit ACTION_START_COMMISSIONING
Abbildung 1: Ablauf der Inbetriebnahme mit ACTION_START_COMMISSIONING

Fügen Sie der ausgewählten Aktivitätsdeklaration in Ihrer AndroidManifest.xml-Datei Folgendes hinzu, um die Unterstützung für die Google-Fabric-Inbetriebnahme anzugeben:intent-filter

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

Mit intent-filter wird Ihre App in die Liste der vorgeschlagenen Matter-Apps in der App-Auswahl der Commissioning APIs aufgenommen. Wenn Ihre App nicht zu den vorgeschlagenen Apps gehört, wird sie unter 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 Stoffe (mehrere Administratoren)

Sie können den Fast Pair-Ablauf auch in Szenarien mit mehreren Administratoren verwenden. Weitere Informationen finden Sie unter Multi-Admin für die Commissioning API auf 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, gibt an, dass der Nutzer entweder den Geräte-QR-Code bereits gescannt oder den Kopplungsschlüssel eingegeben hat. Ein Nutzlastwert von null bedeutet nicht, dass die Inbetriebnahme abgebrochen werden sollte.

Benachrichtigungen zur Provisionierung unterdrücken

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

Standardmäßig werden auf Android Google Play services-Benachrichtigungen im Halbsheet-Format verwendet, die die untere Hälfte des Bildschirms eines Mobilgeräts abdecken, um Nutzern proaktiv anzuzeigen, dass sich provisionsfähige Matter-Geräte in der Nähe befinden.

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

Die durch diese API aktivierte Unterdrückung läuft ab, wenn sich Ihre App länger als 15 Minuten im Vordergrund befindet. Wenn Sie die Unterdrückung nach einem Zeitüberschreitung 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 zum Teilen eines Geräts zu verwenden, das Sie bereits in Ihrem eigenen Fabric eingerichtet haben, mit dem Google-Fabric. 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 das Teilen eines Geräts direkt mit dem 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 wissen, dass er GHA während des Vorgangs auswählen muss, damit er erfolgreich abgeschlossen werden kann.

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

Wann sollte die Share API verwendet werden?

Mit der Share API können Sie Endnutzern die Möglichkeit geben, eine geeignete Anwendung auszuwählen, um ein Gerät allgemein mit anderen Matter-Ökosystemen zu teilen.