Commissioning API di Android

Commissioning API memungkinkan aplikasi untuk menyediakan ke:

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

Cara menyediakan perangkat Matter

Proses penyediaan dapat dimulai:

Meminta penyediaan langsung di aplikasi Anda

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

Untuk satu fabric

Untuk meminta penyediaan:

  1. Inisialisasi ActivityResultLauncher dalam aktivitas Anda. Jika pengguna menyediakan perangkat di fabric Google, hasilnya dapat menyertakan nama yang ditetapkan pengguna ke perangkat saat mereka menyediakannya.

    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 menyediakan perangkat ke fabric Google, menggunakan setStoreToGoogleFabric:

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

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

  3. Gunakan instance untuk memulai penyediaan:CommissioningClient

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

    Dengan _commissioningIntentSender yang 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 Matter fabric di perangkat, lihat Multi-admin untuk Commissioning API di Android.

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

Meminta penyediaan melalui sambungan cepat atau kode QR di Android dapat dilakukan dengan dua cara:

Untuk satu fabric

Gunakan filter intent ACTION_START_COMMISSIONING untuk memberikan kemampuan penyediaan penuh untuk aplikasi tanpa memerlukan GHA. Saat menyediakan ke fabric Google, hal ini mencakup mengizinkan pengguna menetapkan nama ke perangkat.

Menyiapkan Flow Menggunakan ACTION_START_COMMISSIONING
Gambar 1: Alur Penyediaan Menggunakan ACTION_START_COMMISSIONING

Untuk menunjukkan dukungan untuk penyediaan fabric Google, 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 aplikasi Anda bukan salah satu aplikasi yang disarankan, aplikasi tersebut akan muncul di opsi Pilih aplikasi lain.

Setelah pengguna memilih aplikasi Anda, aplikasi Anda 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 mengetahui informasi selengkapnya, lihat Multi-admin untuk Commissioning API di Android.

Menangani intent yang masuk

Setelah diluncurkan, aktivitas Anda harus 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
    }
val commissioningRequest = CommissioningRequest.builder()
          .setOnboardingPayload(payload)
          .setStoreToGoogleFabric(true)
          // set all other options that you care about
          .build()
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 penyediaan harus dibatalkan.

Menyembunyikan notifikasi penemuan yang dapat disediakan

Contoh notifikasi setengah layar Android
Gambar 1: Contoh notifikasi setengah layar Android

Secara default, Google Play services di Android menggunakan "notifikasi setengah layar" yang mencakup bagian bawah layar perangkat seluler untuk memberi pengguna indikasi proaktif bahwa perangkat Matter yang dapat disediakan berada di dekatnya.

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

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

Bagaimana cara membagikan perangkat Matter di fabric Anda ke Google?

Google sangat menyarankan agar Anda menggunakan Commissioning API sebagai cara utama untuk membagikan perangkat yang telah Anda siapkan di fabric Anda sendiri ke fabric Google. Share API memiliki batasan 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 pilihan jika memungkinkan. Dengan Share API, pengguna akhir memerlukan lebih banyak langkah. Misalnya, pengguna akhir harus menginstal GHA, dan mereka harus tahu cara memilih GHA selama proses untuk memastikan keberhasilan.

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

Kapan Anda harus menggunakan Share API?

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