Commissioning API na Androidzie

Interfejs Commissioning API umożliwia udostępnianie aplikacji:

  • Twojej sieci i sieci Google.
  • Tylko sieci Google.

Sposoby udostępniania urządzeń Matter

Proces udostępniania można rozpocząć:

Prośba o udostępnienie bezpośrednio w aplikacji

Prośbę o udostępnienie bezpośrednio w aplikacji można wywołać za pomocą przycisku w aplikacji. Można to zrobić na 2 sposoby:

W przypadku pojedynczych sieci

Aby poprosić o udostępnienie:

  1. Zainicjuj ActivityResultLauncher w swoim działaniu. Jeśli użytkownik udostępnił urządzenie w sieci Google, wynik może zawierać nazwę, którą użytkownik przypisał do urządzenia podczas udostępniania.

    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ę udostępnienia urządzenia w 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 w sieci Google oraz w swojej sieci, ustaw usługę udostępniania za pomocą setCommissioningService w CommissioningRequest.

  3. Aby rozpocząć udostępnianie, użyj CommissioningClient instancji:

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

    Gdzie _commissioningIntentSender jest zdefiniowany 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, przeczytaj artykuł Wielu administratorów w interfejsie Commissioning API na Androidzie.

Punkt wejścia do udostępniania Matter za pomocą Szybkiego parowania lub skanowania kodu QR (tylko na Androidzie)

Prośbę o udostępnienie za pomocą Szybkiego parowania lub kodu QR na Androidzie można wysłać na 2 sposoby:

W przypadku pojedynczych sieci

Użyj filtra intencji ACTION_START_COMMISSIONING , aby zapewnić pełną funkcjonalność udostępniania aplikacji bez konieczności korzystania z aplikacji GHA. W przypadku 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 za pomocą ACTION_START_COMMISSIONING

Aby wskazać obsługę udostępniania w sieci Google, dodaj ten intent-filter do wybranej deklaracji działania 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

intent-filter służy do dodawania aplikacji do listy sugerowanych Matter aplikacji w selektorze aplikacji interfejsów Commissioning API app picker. Jeśli Twoja aplikacja nie jest jedną z sugerowanych aplikacji, pojawi się w opcji Wybierz inną aplikację.

Gdy użytkownik wybierze Twoją aplikację, zostanie ona uruchomiona i przekierowana do wybranego działania z ACTION_START_COMMISSIONING intencją.

W przypadku wielu sieci (wielu administratorów)

W scenariuszach z wieloma administratorami możesz też użyć procesu Szybkiego parowania. Więcej informacji znajdziesz w artykule Wielu administratorów w interfejsie Commissioning API na Androidzie.

Obsługa przychodzącej intencji

Po uruchomieniu działania powinno ono 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, która nie jest równa null, oznacza, że użytkownik zeskanował już kod QR urządzenia lub wpisał klucz parowania. Wartość ładunku null nie oznacza, że należy przerwać udostępnianie.

Wyłączanie powiadomień o wykryciu urządzeń, które można udostępnić

Przykład powiadomienia w formie półarkusza na Androidzie
Rysunek 1. Przykład powiadomienia na pół ekranu na Androidzie

Domyślnie Google Play services na Android używa powiadomień na pół ekranu, 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, które można udostępnić.

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

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

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

Google zdecydowanie zaleca używanie 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 ograniczenia i powinien być zarezerwowany do 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 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ć GHA zainstalowaną i musi wiedzieć, że podczas procesu należy wybrać GHA, aby udostępnianie się powiodło.

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 narzędzia do udostępniania Matter.

Kiedy warto używać interfejsu Share API?

Za pomocą interfejsu Share API możesz umożliwić użytkownikowi wybranie odpowiedniej aplikacji do ogólnego udostępniania urządzenia w innych ekosystemach Matter.