Commissioning API na Androidzie

Interfejs Commissioning API umożliwia aplikacji zlecanie wykonania tych czynności:

  • Tkanina i tkanina Google.
  • Tylko materiał Google.

Sposoby korzystania z urządzeń Matter

Proces uruchamiania może zostać zainicjowany:

Prośba o wdrożenie bezpośrednio w aplikacji

Żądanie uruchomienia procesu komisjonowania bezpośrednio w aplikacji można wywołać za pomocą przycisku w aplikacji. Można to zrobić na 2 sposoby:

Do pojedynczych tkanin

Aby poprosić o wdrożenie:

  1. Zainicjuj ActivityResultLauncher w swojej aktywności. Jeśli użytkownik zamówił urządzenie w Google Fabric, wynik może zawierać nazwę przypisaną do urządzenia podczas jego zamawiania.

    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. Utwórz pakiet CommissioningRequest, w tym dane ładunku, i ustaw opcję zlecenia urządzenia do Google Fabric, używając: setStoreToGoogleFabric

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

    Jeśli chcesz zlecić uruchomienie urządzenia w fabryce Google i w swojej fabryce, skonfiguruj usługę uruchamiania za pomocą setCommissioningService w CommissioningRequest.

  3. Aby rozpocząć wdrażanie, użyj instancji CommissioningClient:

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

    Gdzie _commissioningIntentSender jest zdefiniowana jako:

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

  4. Gdy CommissioningClient zwróci nadawcę intencji, uruchom nadawcę:

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

W przypadku wielu platform (wielu administratorów)

Jeśli chcesz skonfigurować na urządzeniu kilka Matter tkanin, zapoznaj się z artykułem Wieloadministrator w przypadku interfejsu Commissioning API na Androidzie.

Punkt wejścia do konfiguracji Matter w ramach szybkiego parowania lub skanowania kodu QR (tylko Android)

Prośbę o wdrożenie za pomocą szybkiego parowania lub kodu QR na urządzeniu z Androidem można wysłać na 2 sposoby:

Do pojedynczych tkanin

Użyj filtra intencji ACTION_START_COMMISSIONING, aby zapewnić pełną obsługę aplikacji bez konieczności korzystania z funkcji GHA. W przypadku wdrażania w Google fabric oznacza to umożliwienie użytkownikowi nadania nazwy urządzeniu.

Proces uruchamiania za pomocą parametru ACTION_START_COMMISSIONING
Rysunek 1. Proces uruchamiania za pomocą interfejsu ACTION_START_COMMISSIONING

Aby wskazać, że obsługujesz tworzenie komponentów w Google, dodaj te informacje:intent-filter do wybranej deklaracji aktywności w pliku AndroidManifest.xml:

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

intent-filter służy do umieszczania Twojej aplikacji na liście sugerowanych aplikacji Matter w selektorze aplikacji interfejsów API do zlecania. Jeśli Twoja aplikacja nie jest jedną z zalecanych, pojawi się w opcji Wybierz inną aplikację.

Gdy użytkownik wybierze Twoją aplikację, zostanie ona uruchomiona i przekierowany do wybranej aktywności za pomocą ACTION_START_COMMISSIONINGintencji.

W przypadku wielu platform (wielu administratorów)

Możesz też użyć procedury Szybkie parowanie w sytuacjach z wielu administratorami. Więcej informacji znajdziesz w artykule Wieloadministratorzy w ramach interfejsu Commissioning API na Androida.

Obsługa przychodzącej intencji

Po uruchomieniu Twojego działania powinno ono sprawdzić istniejące ACTION_START_COMMISSIONINGintencje i pobrać ładunek:

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

Wartość ładunku, która nie jest null, wskazuje, że użytkownik zeskanował kod QR urządzenia lub wprowadził klucz parowania. Wartość null w danych ładunku nie oznacza, że wdrożenie powinno zostać przerwane.

Wyłączanie powiadomień o możliwości zarobku

Przykład powiadomienia w połowie ekranu na Androidzie
Rysunek 1. Przykład powiadomienia w układce połowy ekranu na Androidzie

Domyślnie Google Play services na Android używa powiadomień typu „pół kartki”, które zajmują dolną połowę ekranu urządzenia mobilnego, aby informować użytkowników o tym, że w pobliżu znajdują się urządzenia Matter, na których można wyświetlać reklamy.

Aby zapobiec przerwom, gdy aplikacja jest na pierwszym planie, możesz ukryć te powiadomienia, wywołując metodę suppressHalfSheetNotification(). Więcej informacji znajdziesz w dokumentacji interfejsu API.

Wyłączenie funkcji obsługiwane przez ten interfejs API wygasa, jeśli aplikacja jest na pierwszym planie przez ponad 15 minut. Aby ponownie włączyć pominięcie po upływie limitu czasu, ponownie wywołaj funkcję suppressHalfSheetNotification(), w przeciwnym razie zaczną się pojawiać powiadomienia na półpełnym ekranie.

Jak udostępniać Google urządzenia Matter w Twoim fabric?

Zdecydowanie zalecamy korzystanie z interfejsu Commissioning API jako głównego środka do udostępniania urządzenia, które zostało już skonfigurowane w Twojej własnej fabric, w Google fabric. Interfejs Share API ma pewne ograniczenia i powinien być zarezerwowany do innych zastosowań.

Dlaczego warto używać interfejsu Commissioning API zamiast interfejsu Share API?

Interfejs Commissioning API umożliwia udostępnianie urządzenia bezpośrednio do architektury Google, co jest preferowaną metodą, jeśli jest to możliwe. W przypadku interfejsu Share API użytkownik musi wykonać więcej czynności. Na przykład użytkownik musi mieć zainstalowaną aplikację GHA i wiedzieć, aby wybrać GHA.

Aby korzystać z interfejsu Commissioning API, należy otworzyć okno komisji i wywołać interfejs Commissioning API zgodnie z opisem w artykule Jak korzystać z interfejsu Commissioning API w przypadku wtórnego komisarza Matter.

Kiedy należy używać interfejsu Share API?

Możesz użyć interfejsu Share API, aby umożliwić użytkownikowi wybranie odpowiedniej aplikacji do udostępniania urządzenia w ogóle innym ekosystemom Matter.