Android'deki Commissioning API

Commissioning API, bir uygulamanın aşağıdakilerden birini yapmasına olanak tanır:

  • Kendi ağınız ve Google ağı.
  • Yalnızca Google kumaşı.

Matter cihazlarını etkinleştirmenin yolları

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

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

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

Tek kumaşlar için

Devreye alma isteğinde bulunmak için:

  1. Etkinliğinizde bir ActivityResultLauncher başlatın. Kullanıcı, cihazı Google Fabric'te devreye aldıysa sonuçta, kullanıcının cihazı devreye alırken cihaza atadığı ad yer alabilir.

    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 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. Devreye almayı 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")
  }

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

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

  4. CommissioningClient, intent gönderenini 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 kumaş için (çoklu yönetici)

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

Hızlı Eşleme veya QR kodu taraması için Matter devreye alma giriş noktası (yalnızca Android)

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

Tek kumaşlar için

GHA'a gerek kalmadan bir uygulama için tam devreye alma özelliği sağlamak üzere ACTION_START_COMMISSIONING intent filtresini kullanın. Google Fabric'e cihazı devreye alırken kullanıcının cihaza bir ad atamasına izin vermek de buna dahildir.

ACTION_START_COMMISSIONING Kullanarak Devreye Alma Akışları
Şekil 1: ACTION_START_COMMISSIONING
Kullanımıyla Devreye Alma Akış Şeması

Google kumaş devreye alma özelliğinin desteklendiğ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 APIs uygulama seçicisinde önerilen Matter uygulamaların listesine dahil etmek için kullanılır. Uygulamanız önerilen uygulamalardan biri değilse Diğer uygulamayı 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'iyle seçilen etkinliğe yönlendirilir.

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

FastPair akışını çok yöneticili senaryolarda 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 intent'i kontrol etmeli ve yük verisini 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
    }
CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
    // set all other options that you care about
startCommissioning(commissioningRequest)
}

null olmayan bir yararlı yük değeri, kullanıcının cihazın QR kodunu zaten 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.

Satış oranına tabi keşif bildirimlerini engelleme

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

Android'daki Google Play services, varsayılan olarak kullanıcılara komisyonlu Matter cihazların yakınlarda olduğunu proaktif bir şekilde belirtmek için mobil cihaz ekranının alt yarısını kaplayan"yarım sayfa" bildirimleri kullanır.

Uygulamanız ön plandayken kesinti yaşamamak için suppressHalfSheetNotification() yöntemini çağırarak bu bildirimleri devre dışı bırakabilirsiniz. Daha fazla bilgi için API belgelerine bakın.

Uygulamanız 15 dakikadan uzun süre ön planda kalırsa bu API tarafından etkinleştirilen engelleme zaman aşımına uğrar. Zaman aşımı süresinden sonra engellemeyi yeniden etkinleştirmek için suppressHalfSheetNotification() numarasını tekrar arayın. Aksi takdirde yarım sayfalık bildirimler görünmeye başlar.

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

Google, kendi kumaşınızda ayarladığınız bir cihazı Google kumaşıyla paylaşmak için birincil aracınız olarak Komisyon API'sini 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.

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

Commissioning API, bir cihazın doğrudan Google Fabric ile paylaşılmasını tetiklemenize olanak tanır. Bu yöntem, uygun olduğunda tercih edilen yöntemdir. Share API'de son kullanıcının daha fazla adım uygulaması gerekir. Örneğin, son kullanıcının GHA yüklü olması ve işlemin başarılı olması için süreç sırasında GHA'yi seçmesi gerekir.

Commissioning API'yi kullanmak için İkincil Matter komisyoncusu olarak Commissioning API'yi kullanma bölümünde açıklandığı gibi, commissioning penceresini açmanız ve Commissioning API'yi çağırmanız gerekir.

Share API'yi ne zaman kullanmalısınız?

Nihai 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.