Android'deki Commissioning API

Commissioning API, bir uygulamanın aşağıdakilerden birine devreye alma işlemi yapmasına olanak tanır:

• Sizin yapınız ve Google yapısı.
• Yalnızca Google yapısı.

Matter cihazlarını yetkilendirme yöntemleri

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

• Doğrudan uygulamanızda
• Android'de Hızlı Eşleme aracılığıyla.

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

Doğrudan uygulamada devreye alma isteği, uygulamadaki bir düğmeyle tetiklenebilir ve iki şekilde yapılabilir:

• Tek kumaşlar için
• Birden fazla kumaş için

Tek kumaşlar için

Devreye alma isteğinde bulunmak için:

1. Etkinliğinizde bir ActivityResultLauncher başlatın. Kullanıcı, cihazı Google yapısında devreye aldıysa sonuç, kullanıcının devreye alırken cihaza 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 yapısına yetkilendirme seçeneğini ayarlayın:

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

   Cihazı kendi yapınızın yanı sıra Google yapısında da devreye almak istiyorsanız devreye alma hizmetinizi CommissioningRequest içinde setCommissioningService ile ayarlayın.

3. Devreye alma işlemini başlatmak 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")
     }
   

   _commissioningIntentSender şu şekilde tanımlanır:

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

4. CommissioningClient, intent göndereni döndürdükten sonra göndereni başlatın:

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

Birden fazla yapı için (çoklu yönetici)

Bir cihazda birden fazla Matter yapısı oluşturmanız gerekiyorsa Android'de Commissioning API için çoklu yönetici başlıklı makaleyi inceleyin.

Hızlı Eşleme veya QR kodu tarama için Matter temel hazırlık giriş noktası (yalnızca Android)

Android'de Hızlı Eşleme veya QR kodu aracılığıyla devreye alma isteği iki şekilde yapılabilir:

• Tek kumaşlar için
• Birden fazla kumaş için

Tek kumaşlar için

GHA olmadan bir uygulamaya tam devreye alma özelliği sağlamak için ACTION_START_COMMISSIONING intent filtresini kullanın. Google yapısına devreye alma sırasında kullanıcının cihaza ad atamasına izin verilmesi de buna dahildir.

Google Fabric devreye alma desteğini belirtmek için AndroidManifest.xml dosyanızdaki seçili etkinlik beyanına aşağıdaki intent-filter öğesini ekleyin:

<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'lerin uygulama seçicisindeki önerilen Matter uygulamaları listesine eklemek için kullanılır. Uygulamanız önerilen uygulamalardan biri değilse Başka uygulama seç seçeneğinde görünür.

Kullanıcı uygulamanızı seçtikten sonra uygulamanız başlatılır ve ACTION_START_COMMISSIONING intent'i ile seçilen etkinliğe yönlendirilir.

Birden fazla yapı için (çoklu yönetici)

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

Gelen intent'i işleme

Etkinliğiniz başlatıldıktan sonra mevcut ACTION_START_COMMISSIONING intent'i 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.

Komisyonlu keşif bildirimlerini engelleme

Varsayılan olarak, Android üzerinde Google Play services, mobil cihaz ekranının alt yarısını kaplayan "yarım sayfa" bildirimleri kullanarak kullanıcılara komisyon alınabilir Matter cihazların yakında olduğunu proaktif olarak gösterir.

Uygulamanız ön plandayken kesinti yaşanmasını önlemek için suppressHalfSheetNotification() yöntemini çağırarak bu bildirimleri gizleyebilirsiniz. Daha fazla bilgi için API belgelerini inceleyin.

Uygulamanız 15 dakikadan uzun süre ön planda kalırsa bu API tarafından etkinleştirilen gizleme işlemi zaman aşımına uğrar. Zaman aşımından sonra gizlemeyi yeniden etkinleştirmek için suppressHalfSheetNotification() yöntemini tekrar çağırın. Aksi takdirde yarım sayfa bildirimler görünmeye başlar.

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

Google, kendi yapınızda zaten ayarladığınız bir cihazı Google yapısıyla paylaşmak için birincil yöntem 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, bir cihazın doğrudan Google yapısıyla paylaşılmasını tetiklemenize olanak tanır. Bu, mümkün olduğunda tercih edilen yöntemdir. Share API ile son kullanıcı için daha fazla adım gerekir. Örneğin, son kullanıcının cihazında GHA yüklü olmalı ve işlemin başarılı olması için süreç sırasında GHA seçeneğini belirlemesi gerektiğini bilmelidir.

Commissioning API'yi kullanmak için devreye alma penceresini açmanız ve İkincil Matter devreye alma sorumlusu olarak Commissioning API'yi kullanma bölümünde açıklandığı şekilde Commissioning API'yi çağırmanız gerekir.

Share API'yi 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.