Android'deki Commissioning API

MatterMatterGoogle Home app (GHA)

Commissioning API, bir uygulamanın aşağıdakilerden birine devreye alınmasına olanak tanır:

  • Kumaşınız ve Google'ın kumaşı.
  • Yalnızca Google kumaşı.

Matter cihazları devreye alma yöntemleri

Devreye alma işlemi şu şekilde başlatılabilir:

Doğrudan uygulamanızda devreye alma isteğinde bulunma

Uygulamada doğrudan devreye alma isteğinde bulunma, uygulamadaki bir düğmeyle tetiklenebilir ve iki şekilde yapılabilir:

Tekstil ürünleri için

Komisyon isteğinde bulunmak için:

  1. Etkinliğinizde bir ActivityResultLauncher başlatın. Kullanıcı, cihazı Google kumaşında devreye aldıysa sonuç, kullanıcının cihazı devreye alırken atadığı adı içerebilir.

    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. Alınan yük verileri de dahil olmak üzere bir CommissioningRequest oluşturun ve setStoreToGoogleFabric kullanarak cihazı Google Fabric'e devreye alma seçeneğini ayarlayın:

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

    Cihazı hem Google kumaşına hem de kendi kumaşınıza devreye almak istiyorsanız CommissioningRequest içinde setCommissioningService ile devreye alma hizmetinizi ayarlayın.

  3. Komisyon vermeye başlamak için CommissioningClient örneğini kullanın:

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

    Burada _commissioningIntentSender şu şekilde tanımlanır:

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

  4. CommissioningClient, niyet gönderenini döndürdüğünde göndereni başlatın:

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

Birden fazla kumaş için (çoklu yönetici)

Bir cihazda birden fazla Matter kumaşı ayarlamanız gerekiyorsa Android'de devreye alma API'si için çoklu yönetici başlıklı makaleyi inceleyin.

Fast Pair veya QR kodu tarama için Matter devreye alma giriş noktası (yalnızca Android)

Android'de hızlı eşleme veya QR kodu aracılığıyla devreye alma isteğinde bulunma işlemi iki şekilde yapılabilir:

Tekstil ürünleri için

ACTION_START_COMMISSIONING intent filtresini kullanarak GHA'a gerek kalmadan bir uygulamaya tam hazırlama özelliği sağlayın. Google kumaşına hazırlama yaparken bu, kullanıcının cihaza ad atamasına izin vermeyi içerir.

ACTION_START_COMMISSIONING kullanarak hizmete alma akışı
Şekil 1: Kullanılarak Yapılandırma Akışı ACTION_START_COMMISSIONING

Google kumaşla devreye alma desteğini belirtmek için intent-filter dosyanızdaki seçilen etkinlik bildirimine aşağıdaki intent-filter öğesini ekleyin: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, uygulamanızı Commissioning API'lerindeki uygulama seçicide önerilen Matter uygulamalar listesine dahil etmek için kullanılır. Uygulamanız önerilen uygulamalar arasında değilse Başka bir uygulama seçin seçeneğinde görünür.

Kullanıcı uygulamanızı seçtiğinde uygulamanız başlatılır ve ACTION_START_COMMISSIONING amacına sahip seçilen etkinliğe yönlendirilir.

Birden fazla kumaş için (çoklu yönetici)

Çoklu yönetici senaryolarında FastPair akışını da kullanabilirsiniz. Daha fazla bilgi için Android'de Commissioning API için çoklu yönetici başlıklı makaleyi inceleyin.

Gelen niyeti işleme

Etkinliğiniz başlatıldıktan sonra mevcut ACTION_START_COMMISSIONING amacını kontrol etmeli ve yükü almalıdır:

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

null olmayan bir yük değeri, kullanıcının cihazın QR kodunu taradığını veya eşleme anahtarını girdiğini gösterir. null yük değeri, devreye alma işleminin iptal edilmesi gerektiği anlamına gelmez.

Komisyon kazandıran keşif bildirimlerini engelleme

Android yarım sayfa bildirimi örneği
Şekil 1: Android'de yarım sayfa bildirim örneği

Google Play services on Android, varsayılan olarak kullanıcıları yakında komisyon kazanmaya uygun Matter cihazlar olduğu konusunda proaktif olarak bilgilendirmek için mobil cihaz ekranının alt yarısını kaplayan "yarım sayfa" bildirimlerini kullanır.

Uygulamanız ön plandayken kesintileri önlemek için suppressHalfSheetNotification() yöntemini çağırarak bu bildirimleri bastırabilirsiniz. Daha fazla bilgi için API belgelerini inceleyin.

Bu API tarafından etkinleştirilen bastırma, uygulamanız 15 dakikadan uzun süre ön planda kalırsa zaman aşımına uğrar. Zaman aşımından sonra bastırmayı yeniden etkinleştirmek için suppressHalfSheetNotification() işlevini tekrar çağırın. Aksi takdirde, yarım sayfa bildirimleri görünmeye başlar.

Matter cihazları Google ile nasıl paylaşmalısınız?

Google, kendi kumaşınızda daha önce ayarladığınız bir cihazı Google kumaşıyla paylaşmanın birincil yolu olarak Commissioning API'yi kullanmanızı önemle tavsiye eder. Share API'nin sınırlamaları vardır ve diğer kullanım alanları için ayrılmalıdır.

Neden Share API yerine Commissioning API'yi kullanmalısınız?

Commissioning API, uygun olduğunda tercih edilen yöntem olan cihaz paylaşımını doğrudan Google Fabric ile tetiklemenize olanak tanır. Paylaşım API'si ile son kullanıcının daha fazla adım gerçekleştirmesi gerekir. Örneğin, son kullanıcının GHA uygulamasını yüklemiş olması ve başarılı bir işlem için süreç sırasında GHA seçmesi gerektiğini bilmesi gerekir.

Commissioning API'yi kullanmak için How to use the Commissioning API as the secondary Matter commissioner (Commissioning API'yi ikincil Matter komisyoneri olarak kullanma) başlıklı makalede açıklandığı gibi, komisyon verme penceresini açıp Commissioning API'yi çağırmanız gerekir.

Paylaşım API'sini ne zaman kullanmalısınız?

Son kullanıcının, bir cihazı diğer Matter ekosistemleriyle genel olarak paylaşmak için uygun bir uygulama seçmesine izin vermek üzere Share API'yi kullanabilirsiniz.