Commissioning API na Androidzie

Interfejs Commissioning API umożliwia aplikacji dodanie urządzenia do:

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

Sposoby uruchamiania urządzeń Matter

Proces dodawania można rozpocząć:

Prośba o uruchomienie bezpośrednio w aplikacji

Prośbę o uruchomienie bezpośrednio w aplikacji można wywołać za pomocą przycisku w aplikacji na 2 sposoby:

Pojedyncze tkaniny

Aby poprosić o uruchomienie:

  1. Zainicjuj ActivityResultLauncher w aktywności. Jeśli użytkownik uruchomił urządzenie w sieci Google, wynik może zawierać nazwę przypisaną przez użytkownika do urządzenia podczas jego uruchamiania.

    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 obiekt CommissioningRequest, w tym otrzymane dane ładunku, i ustaw opcję dodawania urządzenia do sieci Google za pomocą setStoreToGoogleFabric:

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

    Jeśli chcesz udostępnić urządzenie zarówno w sieci Google, jak i we własnej sieci, ustaw usługę udostępniania na setCommissioningService w CommissioningRequest.

  3. Aby rozpocząć uruchamianie, 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 szkieletowych (wielu administratorów)

Jeśli musisz skonfigurować wiele sieci Matter na urządzeniu, zapoznaj się z artykułem Multi-admin for Commissioning API on Android (w języku angielskim).

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 Androidzie można przesłać na 2 sposoby:

Pojedyncze tkaniny

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

Proces uruchamiania z użyciem ACTION_START_COMMISSIONING
Rysunek 1. Proces udostępniania z użyciem ACTION_START_COMMISSIONING

Aby wskazać obsługę dodawania do sieci Google, dodaj ten element 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 uwzględniania aplikacji na liście sugerowanych aplikacji Matter w selektorze aplikacji interfejsów API do obsługi urządzeń. Jeśli Twojej aplikacji nie ma wśród sugerowanych, pojawi się ona w opcji Wybierz inną aplikację.

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

W przypadku wielu sieci szkieletowych (wielu administratorów)

Możesz też użyć procesu Szybkiego parowania w scenariuszach z wieloma administratorami. Więcej informacji znajdziesz w artykule Multi-admin for Commissioning API on Android (w języku angielskim).

Obsługa intencji przychodzącej

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

Pomijaj powiadomienia o odkrywaniu prowizji

Przykład powiadomienia na połowie ekranu na Androidzie
Rysunek 1. Przykład powiadomienia na połowie ekranu na urządzeniu z Androidem

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

Aby uniknąć przerw, gdy aplikacja działa na pierwszym planie, możesz wyłączyć te powiadomienia, wywołując metodę suppressHalfSheetNotification(). Więcej informacji znajdziesz w dokumentacji interfejsu API.

Jeśli aplikacja jest na pierwszym planie przez ponad 15 minut, wyciszenie włączone przez ten interfejs API zostanie wyłączone. Aby ponownie włączyć pomijanie po upływie limitu czasu, wywołaj jeszcze raz suppressHalfSheetNotification(). W przeciwnym razie zaczną się pojawiać powiadomienia na połowie ekranu.

Jak udostępnić Google urządzenia Matter w sieci?

Google zdecydowanie zaleca używanie interfejsu Commissioning API jako głównego sposobu udostępniania urządzenia, które zostało już skonfigurowane we własnej sieci, w sieci Google. Interfejs Share API ma swoje ograniczenia i powinien być używany w innych przypadkach.

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

Interfejs Commissioning API umożliwia uruchomienie udostępniania urządzenia bezpośrednio w sieci 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 musi wiedzieć, że podczas procesu musi wybrać GHA, aby wszystko przebiegło pomyślnie.

Aby użyć interfejsu Commissioning API, otwórz okno udostępniania i wywołaj interfejs Commissioning API zgodnie z opisem w artykule Jak używać interfejsu Commissioning API jako dodatkowego administratora 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 ogólnego udostępniania urządzenia innym ekosystemom Matter.