Inbetriebnahme der API

Mit der Commissioning API kann eine App entweder

  • Ihre Fabric und die Google Fabric.
  • Nur Google Fabric.

Unterstützung für die Matter-Inbetriebnahme angeben

Wenn Sie die Google Home Mobile SDK zur Inbetriebnahme verwenden, müssen Sie den Namen des App-Pakets in der Google Home Developer Console hinzufügen, unsere Matter APIs implementieren und angeben, dass Ihre App die Matter-Inbetriebnahme unterstützt, indem Sie den ACTION_COMMISSION_DEVICE-Intent verarbeiten.

Fügen Sie der application-Deklaration in der Datei AndroidManifest.xml die folgende intent-filter hinzu:

<intent-filter>
    <action android:name="com.google.android.gms.metadata.MODULE_DEPENDENCIES" />
</intent-filter>

Weitere Informationen finden Sie im Manifest unserer Beispiel-App.

Möglichkeiten zur Inbetriebnahme von Matter-Geräten

Die Inbetriebnahme kann so gestartet werden:

In Ihrer App die Inbetriebnahme anfordern

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

Für einzelne Stoffe

So fordern Sie die Inbetriebnahme an:

  1. Initialisieren Sie eine ActivityResultLauncher in Ihrer Aktivität. Wenn der Nutzer das Gerät in Google Fabric in Betrieb genommen hat, enthält das Ergebnis möglicherweise den Namen, 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 eine CommissioningRequest, einschließlich der empfangenen Nutzlastdaten, und setze die Option, das Gerät für die Google-Fabric zu initiieren, mit setStoreToGoogleFabric:

    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 die Google Fabric als auch für Ihre eigene Fabric in Betrieb nehmen möchten, legen Sie Ihren Inbetriebnahmedienst mit setCommissioningService in der CommissioningRequest fest.

  3. Verwenden Sie die Instanz CommissioningClient, 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 Fabrics (mehrere Administratoren)

Wenn Sie mehrere Matter-Fabrics auf einem Gerät einrichten möchten, lesen Sie den Hilfeartikel Kommissionierungs-APIs im Modus mit mehreren Administratoren verwenden.

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

Die Inbetriebnahme per Schnelles Pairing oder QR-Code auf Android-Geräten kann auf zwei Arten angefordert werden:

Für einzelne Stoffe

Verwenden Sie den Intent-Filter ACTION_START_COMMISSIONING, um eine vollständige Inbetriebnahme für eine App zu ermöglichen, ohne dass der GHA erforderlich ist. Bei der Inbetriebnahme in Google Fabric muss der Nutzer dem Gerät einen Namen zuweisen können.

Einrichtungsablauf mit ACTION_START_COMMISSIONING
Abbildung 1: Einrichtungsablauf mit ACTION_START_COMMISSIONING

Wenn Sie die Unterstützung für die Google Fabric-Inbetriebnahme angeben möchten, fügen Sie der ausgewählten Aktivitätsdeklaration in Ihrer AndroidManifest.xml-Datei Folgendes hinzu: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 dem 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 ausgewählt hat, wird sie gestartet und mit einer ACTION_START_COMMISSIONING-Intention zur ausgewählten Aktivität weitergeleitet.

Für mehrere Fabrics (mehrere Administratoren)

Sie können den FastPair-Vorgang auch in Szenarien mit mehreren Administratoren verwenden. Weitere Informationen finden Sie unter Kommissionierungs-APIs im Modus mit mehreren Administratoren verwenden.

Eingehenden Intent verarbeiten

Sobald Ihre Aktivität gestartet wurde, sollte sie nach der vorhandenen ACTION_START_COMMISSIONING-Intention 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 QR-Code des Geräts gescannt oder den Kopplungsschlüssel eingegeben hat. Ein Nutzlastwert von null bedeutet nicht, dass die Inbetriebnahme abgebrochen werden sollte.

Benachrichtigungen zu Entdeckungen mit Provisionsmöglichkeit unterdrücken

Beispiel für eine Android-Halbflächenbenachrichtigung
Abbildung 1: Beispiel für eine Android-Benachrichtigung im Halfsheet-Format

Standardmäßig werden bei Google Play services auf Android „Halbseitenbenachrichtigungen“ verwendet, die die untere Hälfte des Bildschirms eines Mobilgeräts bedecken. So werden Nutzer proaktiv darüber informiert, dass sich in der Nähe Geräte mit Matter befinden, für die eine Provision infrage kommt.

Wenn Sie Unterbrechungen vermeiden möchten, während Ihre App im Vordergrund ist, können Sie diese Benachrichtigungen unterdrücken, indem Sie die Methode suppressHalfSheetNotification() in der Mobile SDK 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 Ablauf der Zeitüberschreitung wieder aktivieren möchten, rufen Sie suppressHalfSheetNotification() noch einmal auf. Andernfalls werden Benachrichtigungen im halben Display angezeigt.

Eine Implementierung dieser API finden Sie im Google Home Sample App for Matter. Weitere Informationen finden Sie unter HalfSheetSuppressionObserver.kt.

Wie sollten Sie Matter-Geräte in Ihrer Fabric mit Google teilen?

Google empfiehlt dringend, die Commissioning API als primäres Mittel zur Freigabe eines Geräts zu verwenden, das Sie bereits in Ihrer eigenen Fabric eingerichtet haben, für die 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 die Freigabe eines Geräts direkt mit Google Fabric auslösen. Dies ist die bevorzugte Methode, wenn dies möglich ist. Bei der Share API sind für den Endnutzer mehr Schritte erforderlich. Beispielsweise muss der Endnutzer GHA installiert haben und wissen, dass er während des Vorgangs GHA auswählen muss, um den Erfolg sicherzustellen.

Wenn Sie die Commissioning API verwenden möchten, müssen Sie das Fenster für die Inbetriebnahme öffnen und die Commissioning API aufrufen, wie unter Commissioning API als sekundärer Matter-Koordinator 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 mit anderen Matter-Systemen zu teilen.

Zurück
Fehlerbehebung
Weiter
Mehrere Administratoren