Commissioning API na Androidzie

Interfejs Commissioning API umożliwia aplikacji uruchomienie urządzenia w jednym z tych trybów:

• Twoja sieć i sieć Google.
• Tylko tkanina Google.

Sposoby uruchamiania urządzeń Matter

Proces uruchamiania można zainicjować:

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

Prośba o prowizję bezpośrednio w aplikacji

Żądanie uruchomienia bezpośrednio w aplikacji może być wywoływane przez przycisk w aplikacji i może być realizowane na 2 sposoby:

• W przypadku pojedynczych tkanin
• W przypadku wielu tkanin

Pojedyncze tkaniny

Aby poprosić o uruchomienie:

1. Zainicjuj ActivityResultLauncher w swojej aktywności. Jeśli użytkownik skonfigurował urządzenie w sieci Google, wynik może zawierać nazwę, którą użytkownik przypisał do urządzenia podczas konfiguracji.

   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ę włączenia urządzenia w sieć Google za pomocą setStoreToGoogleFabric:

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

   Jeśli chcesz przekazać urządzenie do sieci Google i do własnej sieci, ustaw usługę przekazywania 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 zdefiniowane jako:

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

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

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

W przypadku wielu sieci (wielu administratorów)

Jeśli musisz skonfigurować na urządzeniu kilka sieci Matter, zapoznaj się z artykułem Wielu administratorów w przypadku interfejsu Commissioning API na Androidzie.

Punkt wejścia do uruchamiania Matter w przypadku szybkiego parowania lub skanowania kodu QR (tylko na Androidzie)

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

• W przypadku pojedynczych tkanin
• W przypadku wielu tkanin

Pojedyncze tkaniny

Użyj filtra intencji ACTION_START_COMMISSIONING, aby zapewnić pełną możliwość uruchomienia aplikacji bez konieczności używania GHA. Podczas udostępniania w sieci Google obejmuje to umożliwienie użytkownikowi przypisania nazwy do urządzenia.

Aby wskazać obsługę inicjowania z użyciem tkaniny Google, dodaj ten kod 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 aplikacji na liście sugerowanychMatter aplikacji w selektorze aplikacji interfejsów Commissioning API. Jeśli Twojej aplikacji nie ma wśród sugerowanych aplikacji, pojawi się ona w opcji Wybierz inną aplikację.

Gdy użytkownik wybierze Twoją aplikację, zostanie ona uruchomiona i przekierowana do wybranej aktywności z ACTION_START_COMMISSIONING intencją.

W przypadku wielu sieci (wielu administratorów)

Możesz też używać procesu FastPair w scenariuszach z wieloma administratorami. Więcej informacji znajdziesz w artykule Wielu administratorów w przypadku interfejsu Commissioning API na Androidzie.

Obsługa przychodzącej intencji

Po uruchomieniu aktywności powinna ona sprawdzić, czy istnieje intencja ACTION_START_COMMISSIONING 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 inna niż null oznacza, że użytkownik zeskanował już kod QR urządzenia lub wpisał klucz parowania. Wartość ładunku null nie oznacza, że należy przerwać uruchamianie.

Wyłączanie powiadomień o odkrywaniu treści, za które można otrzymać prowizję

Domyślnie Google Play services na Android używa powiadomień „halfsheet”, które zajmują dolną połowę ekranu urządzenia mobilnego, aby aktywnie informować użytkowników o tym, że w pobliżu znajdują się urządzenia Matter, za które można otrzymać prowizję.

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

Wyciszenie włączone przez ten interfejs API wygasa, jeśli aplikacja jest na pierwszym planie przez ponad 15 minut. Aby ponownie włączyć pomijanie po upływie limitu czasu, ponownie wywołaj funkcję suppressHalfSheetNotification(). W przeciwnym razie zaczną się pojawiać powiadomienia o półarkuszu.

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

Google zdecydowanie zaleca korzystanie z interfejsu Commissioning API jako głównego sposobu udostępniania urządzenia, które zostało już skonfigurowane w Twojej sieci, w sieci Google. Interfejs Share API ma swoje ograniczenia i powinien być zarezerwowany dla innych przypadków użycia.

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

Interfejs Commissioning API umożliwia bezpośrednie udostępnianie urządzenia w strukturze Google, co jest preferowaną metodą, gdy 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ć, że w trakcie procesu musi wybrać GHA, aby wszystko przebiegło prawidłowo.

Aby użyć interfejsu Commissioning API, otwórz okno uruchamiania i wywołaj interfejs Commissioning API zgodnie z opisem w artykule Jak używać interfejsu Commissioning API jako dodatkowego komisarza Matter.

Kiedy warto używać interfejsu Share API?

Za pomocą interfejsu Share API możesz umożliwić użytkownikowi końcowemu wybranie odpowiedniej aplikacji do ogólnego udostępniania urządzenia innym ekosystemom Matter.