Commissioning API unter Android

Mit der Commissioning API kann eine App Folgendes in Betrieb nehmen:

  • Ihre Fabric und die Google-Fabric.
  • Nur der Google-Stoff.

Möglichkeiten zur Inbetriebnahme von Matter-Geräten

Der Inbetriebnahmevorgang kann folgendermaßen gestartet werden:

Inbetriebnahme direkt in der App anfordern

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

Für einzelne Stoffe

So fordern Sie die Inbetriebnahme an:

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

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

    Wenn du das Gerät sowohl in der Google-Fabric als auch in deiner eigenen Fabric in Betrieb nehmen möchtest, lege deinen Inbetriebnahme-Dienst mit setCommissioningService in der CommissioningRequest fest.

  3. Verwenden Sie die Instanz CommissioningClient, um mit der Inbetriebnahme zu beginnen:

    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 der CommissioningClient den Intent-Sender zurückgibt, starte den Sender:

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

Für mehrere Fabrics (mehrere Administratoren)

Wenn du mehrere Matter-Fabrics auf einem Gerät einrichten musst, lies den Artikel Multi-Admin für die Commissioning API unter Android.

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

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

Für einzelne Stoffe

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

Inbetriebnahmeablauf mit ACTION_START_COMMISSIONING
Abbildung 1: Inbetriebnahme mit ACTION_START_COMMISSIONING

Wenn du die Unterstützung für die Google Fabric-Inbetriebnahme angeben möchtest, füge der ausgewählten Aktivitätsdeklaration in deiner AndroidManifest.xml-Datei 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 deine 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 unter der Option Andere App auswählen angezeigt.

Sobald der Nutzer deine App auswählt, wird sie gestartet und mit einem ACTION_START_COMMISSIONING-Intent an die ausgewählte Aktivität weitergeleitet.

Für mehrere Fabrics (mehrere Administratoren)

Du kannst den Fast Pair-Ablauf auch in Multi-Admin-Szenarien verwenden. Weitere Informationen findest du unter Multi-Admin für die Commissioning API unter Android.

Eingehenden Intent verarbeiten

Sobald die 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
    }
val commissioningRequest = CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
          // set all other options that you care about
          .build()
startCommissioning(commissioningRequest)
}

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

Benachrichtigungen zu provisionspflichtigen Entdeckungen unterdrücken

Beispiel für eine Android-Halfsheet-Benachrichtigung
Abbildung 1: Beispiel für eine Android-Halbseitenbenachrichtigung

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

Wenn Sie Unterbrechungen vermeiden 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 wird beendet, wenn sich Ihre App länger als 15 Minuten im Vordergrund befindet. Wenn Sie die Unterdrückung nach einer Zeitüberschreitung wieder aktivieren möchten, rufen Sie suppressHalfSheetNotification() noch einmal auf. Andernfalls werden wieder Halfsheet-Benachrichtigungen angezeigt.

Wie solltest du Matter-Geräte in deiner Fabric mit Google teilen?

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

Warum solltest du die Commissioning API anstelle der Share API verwenden?

Mit der Commissioning API kannst du das Teilen eines Geräts direkt mit der Google-Fabric auslösen. Dies ist die bevorzugte Methode, sofern möglich. Bei der Share API sind für den Endnutzer mehr Schritte erforderlich. Der Endnutzer muss beispielsweise GHA installiert haben und wissen, dass er während des Vorgangs GHA auswählen muss, damit der Vorgang erfolgreich ist.

Wenn du die Commissioning API verwenden möchtest, öffne das Inbetriebnahme-Fenster und rufe die Commissioning API auf, wie unter Commissioning API als sekundären Matter-Commissioner verwenden beschrieben.

Wann sollte die Share API verwendet werden?

Mit der Share API kannst du dem Endnutzer die Möglichkeit geben, eine geeignete Anwendung auszuwählen, um ein Gerät allgemein mit anderen Matter-Ökosystemen zu teilen.