API Commissioning

Commissioning API memungkinkan aplikasi melakukan komisi ke:

  • Fabric Anda dan fabric Google.
  • Hanya fabric Google.

Menunjukkan dukungan untuk commissioning Matter

Jika menggunakan Google Home Mobile SDK untuk melakukan komisi, Anda harus menambahkan nama paket aplikasi di Google Home Developer Console, mengimplementasikan API Matter kami, dan menunjukkan bahwa aplikasi Anda mendukung komisi Matter dengan menangani intent ACTION_COMMISSION_DEVICE.

Tambahkan intent-filter berikut ke deklarasi application dalam file AndroidManifest.xml Anda:

<intent-filter>
    <action android:name="com.google.android.gms.metadata.MODULE_DEPENDENCIES" />
</intent-filter>

Lihat manifes aplikasi contoh kami untuk referensi.

Cara melakukan commissioning untuk perangkat Matter

Proses komisi dapat dimulai:

Meminta komisi langsung di aplikasi Anda

Meminta komisi langsung di aplikasi dapat dipicu oleh tombol di aplikasi, dan dapat dilakukan dengan dua cara:

Untuk satu kain

Untuk meminta komisi:

  1. Lakukan inisialisasi ActivityResultLauncher dalam aktivitas Anda. Jika pengguna melakukan commissioning perangkat di Google Fabric, hasilnya dapat menyertakan nama yang ditetapkan pengguna ke perangkat saat mereka melakukan commissioning.

    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. Buat CommissioningRequest, termasuk data payload yang diterima, dan tetapkan opsi untuk melakukan komisi perangkat ke Google Fabric, menggunakan setStoreToGoogleFabric:

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

    Jika Anda ingin mengonfigurasi perangkat ke fabric Google serta fabric Anda sendiri, tetapkan layanan komisi dengan setCommissioningService di CommissioningRequest.

  3. Gunakan instance CommissioningClient untuk memulai komisi:

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

    Dengan _commissioningIntentSender ditentukan sebagai:

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

  4. Setelah CommissioningClient menampilkan pengirim intent, luncurkan pengirim:

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

Untuk beberapa fabric (multi-admin)

Jika Anda perlu menyiapkan beberapa fabric Matter di perangkat, lihat Cara menggunakan API commissioning dalam mode multi-admin.

Titik entri commissioning Matter untuk Sambungan Cepat atau pemindaian kode QR (khusus Android)

Meminta komisi melalui penyambungan cepat atau kode QR di Android dapat dilakukan dengan dua cara:

Untuk satu kain

Gunakan filter intent ACTION_START_COMMISSIONING untuk memberikan kemampuan komisi penuh untuk aplikasi tanpa memerlukan GHA. Saat melakukan commissioning ke Google Fabric, tindakan ini termasuk mengizinkan pengguna menetapkan nama ke perangkat.

Alur Commissioning Menggunakan ACTION_START_COMMISSIONING
Gambar 1: Alur Komisi Menggunakan ACTION_START_COMMISSIONING

Untuk menunjukkan dukungan untuk commissioning Google Fabric, tambahkan intent-filter berikut ke deklarasi aktivitas yang dipilih dalam file AndroidManifest.xml Anda:

<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 digunakan untuk menyertakan aplikasi Anda dalam daftar aplikasi Matter yang disarankan di pemilih aplikasi Commissioning API. Jika bukan salah satu aplikasi yang disarankan, aplikasi Anda akan muncul di opsi Pilih aplikasi lain.

Setelah pengguna memilih aplikasi Anda, aplikasi akan diluncurkan dan diarahkan ke aktivitas yang dipilih dengan intent ACTION_START_COMMISSIONING.

Untuk beberapa fabric (multi-admin)

Anda juga dapat menggunakan alur Sambungan Cepat dalam skenario multi-admin. Untuk informasi selengkapnya, lihat Cara menggunakan API commissioning dalam mode multi-admin.

Menangani intent yang masuk

Setelah diluncurkan, aktivitas Anda akan memeriksa intent ACTION_START_COMMISSIONING yang ada dan mengambil payload:

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

Nilai payload yang bukan null menunjukkan bahwa pengguna telah memindai kode QR perangkat, atau memasukkan kunci penyambungan. Nilai payload null tidak berarti bahwa commissioning harus dibatalkan.

Menyembunyikan notifikasi penemuan yang dapat menghasilkan komisi

Contoh notifikasi halfsheet Android
Gambar 1: Contoh notifikasi halfsheet Android

Secara default, Google Play services di Android menggunakan notifikasi "halfsheet" yang mencakup paruh bawah layar perangkat seluler untuk memberi pengguna indikasi proaktif bahwa perangkat Matter yang dapat memperoleh komisi berada di sekitar.

Untuk mencegah gangguan saat aplikasi berada di latar depan, Anda dapat menyembunyikan notifikasi ini dengan memanggil metode suppressHalfSheetNotification() di Mobile SDK. Lihat dokumentasi API untuk mengetahui informasi selengkapnya.

Penekanan yang diaktifkan oleh API ini akan habis waktu tunggunya jika aplikasi Anda berada di latar depan selama lebih dari 15 menit. Untuk mengaktifkan kembali penekanan setelah waktu tunggu habis, panggil suppressHalfSheetNotification() lagi. Jika tidak, notifikasi halfsheet akan mulai muncul.

Implementasi API ini dapat ditemukan di Google Home Sample App for Matter. Lihat HalfSheetSuppressionObserver.kt untuk mengetahui informasi selengkapnya.

Bagaimana cara membagikan perangkat Matter di fabric Anda kepada Google?

Google sangat menyarankan agar Anda menggunakan Commissioning API sebagai cara utama untuk berbagi perangkat yang telah Anda siapkan di fabric Anda sendiri dengan fabric Google. Share API memiliki keterbatasan dan harus dicadangkan untuk kasus penggunaan lainnya.

Mengapa Anda harus menggunakan Commissioning API, bukan Share API?

Commissioning API memungkinkan Anda memicu berbagi perangkat langsung dengan fabric Google, yang merupakan metode yang lebih disukai jika memungkinkan. Dengan Share API, lebih banyak langkah yang diperlukan untuk pengguna akhir. Misalnya, pengguna akhir harus menginstal GHA, dan mereka harus tahu untuk memilih GHA selama proses untuk memastikan keberhasilan.

Untuk menggunakan Commissioning API, Anda harus membuka jendela commissioning dan memanggil Commissioning API, seperti yang dijelaskan dalam Cara menggunakan Commissioning API sebagai komisaris Matter sekunder.

Kapan Anda harus menggunakan Share API?

Anda dapat menggunakan Share API agar pengguna akhir dapat memilih aplikasi yang memenuhi syarat untuk berbagi perangkat secara umum dengan ekosistem Matter lainnya.

Sebelumnya
Pemecahan masalah
Berikutnya
Multi-admin