Interfejs API do uruchamiania zadań

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

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

Wspieranie tworzenia Matter

Jeśli używasz Google Home Mobile SDK do zlecania, musisz dodać nazwę pakietu aplikacji w Google Home Developer Console, zaimplementować nasze MatterAPI i wskazywać, że Twoja aplikacja obsługuje zlecanie Matter, obsługując intencję ACTION_COMMISSION_DEVICE.

Dodaj do deklaracji application w pliku AndroidManifest.xml te wartości:intent-filter

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

Przykładowy plik manifestu aplikacji

Sposoby korzystania z urządzeń Matter

Proces uruchamiania może zostać zainicjowany:

• Bezpośrednio w aplikacji
• Za pomocą Szybkiego parowania na Androidzie.

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

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

• Tkaniny pojedyncze
• W przypadku wielu materiałów

Do pojedynczych materiałów

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 CommissioningRequest, w tym otrzymane 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 własnej 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, zapoznaj się z artykułem Jak korzystać z interfejsów API do konfigurowania w trybie wielu administratorów.

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:

• Tkaniny pojedyncze
• W przypadku wielu materiałów

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 ramach platformy Google należy umożliwić użytkownikowi nadanie nazwy urządzeniu.

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 Korzystanie z interfejsów API do uruchamiania w trybie wielu administratorów.

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

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, które mogą generować prowizję.

Aby uniknąć przerw, gdy aplikacja jest na pierwszym planie, możesz ukryć te powiadomienia, wywołując metodę suppressHalfSheetNotification() w Mobile SDK. 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.

Implementację tego interfejsu API znajdziesz w Google Home Sample App for Matter. Więcej informacji znajdziesz w sekcji HalfSheetSuppressionObserver.kt.

Jak udostępniać Google urządzenia Matter w ramach usługi fabric?

Zdecydowanie zalecamy używanie interfejsu Commissioning API jako głównego środka udostępniania urządzenia, które zostało już skonfigurowane w Twojej własnej usłudze, usłudze Google. 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, otwórz okno komisjonowania i wywołaj interfejs Commissioning API zgodnie z opisem w artykule Jak korzystać z interfejsu Commissioning API jako drugi komisjoner 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ólnym zakresie innym ekosystemom Matter.