Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Thread Network SDK untuk Android

Thread Network SDK menyediakan fungsi yang mirip dengan gantungan kunci digital, sehingga memungkinkan aplikasi Android Anda membagikan kredensial jaringan Thread dengan layanan Google Play. Hal ini memungkinkan aplikasi Anda menyiapkan perangkat Thread apa pun dari ekosistem smart home mana pun, tanpa mengekspos kredensial dan data pengguna secara langsung.

Hanya dengan beberapa panggilan API, Anda dapat:

Meminta kredensial jaringan Thread pilihan dari layanan Google Play.
Siapkan Thread Border Router (TBR) baru dan tambahkan kredensial jaringan Thread Anda ke layanan Google Play.
Jika sudah memiliki TBR di lapangan, Anda dapat memeriksa apakah TBR Anda berada di jaringan pilihan dan memigrasikannya, jika perlu.

Ada beberapa perjalanan pengguna dan developer yang perlu dipertimbangkan. Kita akan membahas sebagian besar fitur tersebut dalam panduan ini, beserta fitur utama lainnya dan penggunaan yang direkomendasikan.

Terminologi dan konsep API utama

Sebelum memulai, sebaiknya pahami istilah berikut:

Kredensial Jaringan Thread: Blob biner TLV Thread yang mengenkode Nama Jaringan Thread, Kunci Jaringan, dan properti lain yang diperlukan oleh perangkat Thread untuk bergabung ke jaringan Thread tertentu.
Kredensial Jaringan Thread Pilihan: Kredensial jaringan Thread yang dipilih secara otomatis yang dapat dibagikan ke aplikasi dari berbagai vendor menggunakan API getPreferredCredentials.
ID Agen Perbatasan: ID unik global 16 byte untuk TBR perangkat. ID ini dibuat dan dikelola oleh vendor border router.
Aplikasi penyiapan TBR: Ini adalah aplikasi Android Anda yang menyiapkan perangkat TBR baru dan menambahkan kredensial jaringan Thread ke layanan Google Play. Aplikasi Anda adalah pemilik kredensial yang ditambahkan dan memiliki akses ke kredensial tersebut.

Banyak Thread Network API menampilkan Task yang selesai secara asinkron. Anda dapat menggunakan addOnSuccessListener dan addOnFailureListener untuk mendaftarkan callback guna menerima hasil. Untuk mempelajari lebih lanjut, lihat dokumentasi Task.

Kepemilikan dan pemeliharaan kredensial

Aplikasi yang menambahkan kredensial jaringan Thread menjadi pemilik kredensial, dan memiliki izin penuh untuk mengakses kredensial. Jika Anda mencoba mengakses kredensial yang ditambahkan oleh aplikasi lain, Anda akan menerima PERMISSION_DENIED error.

Sebagai pemilik aplikasi, sebaiknya Anda selalu memperbarui kredensial yang disimpan di layanan Google Play saat jaringan TBR diperbarui. Artinya, menambahkan kredensial saat diperlukan, memperbarui kredensial saat kredensial jaringan Thread border router berubah, dan menghapus kredensial saat TBR dihapus atau direset ke setelan pabrik.

Penemuan Agen Batas

Kredensial harus disimpan dengan ID Agen Perbatasan. Anda harus memastikan bahwa aplikasi penyiapan TBR Anda dapat menentukan ID Agen Border TBR Anda.

TBR harus menggunakan mDNS untuk mengiklankan informasi jaringan Thread, termasuk Nama Jaringan, ID Pan yang Diperluas, dan ID Agen Pembatas. Nilai txt yang sesuai untuk atribut ini adalah nn, xp, dan id.

Untuk jaringan dengan Google Thread Border Router (gTBR), layanan Google Play secara otomatis mendapatkan kredensial jaringan Thread Google untuk digunakan.

Mengintegrasikan SDK ke dalam aplikasi Android Anda

Untuk memulai, selesaikan langkah-langkah berikut:

Ikuti petunjuk yang diberikan di Menyiapkan layanan Google Play.

Tambahkan dependensi layanan Google Play ke file build.gradle Anda:

implementation 'com.google.android.gms:play-services-threadnetwork:16.2.1'

Opsional: Tentukan kelas data BorderAgent untuk menyimpan informasi TBR. Kami akan menggunakan data ini di seluruh panduan ini:

data class BorderAgentInfo(
  // Network Name max 16 len
  val networkName: String = "",
  val extPanId: ByteArray = ByteArray(16),
  val borderAgentId: ByteArray = ByteArray(16),
  ...
)

Selanjutnya, kita akan membahas langkah-langkah yang direkomendasikan untuk menambahkan dan mengelola kredensial pilihan.

Penyiapan Router Pembatas Thread baru

Sebelum membuat jaringan baru untuk router batas baru, Anda harus mencoba menggunakan kredensial jaringan pilihan terlebih dahulu. Tindakan ini memastikan bahwa perangkat Thread terhubung ke satu jaringan Thread jika memungkinkan.

Panggilan ke getPreferredCredentials meluncurkan Aktivitas, yang meminta pengguna untuk mengizinkan permintaan jaringan. Jika kredensial jaringan telah disimpan di rantai kunci digital Thread SDK, kredensial akan dikembalikan ke aplikasi Anda.

Meminta kredensial

Untuk meminta kredensial pilihan pengguna:

Deklarasikan ActivityLauncher:

private lateinit var preferredCredentialsLauncher: ActivityResultLauncher<IntentSenderRequest>

Tangani hasil Aktivitas, yang ditampilkan sebagai ThreadNetworkCredentials:

preferredCredentialsLauncher =
 registerForActivityResult(
   StartIntentSenderForResult()
 ) { result: ActivityResult ->
   if (result.resultCode == RESULT_OK) {
     val threadNetworkCredentials = ThreadNetworkCredentials.fromIntentSenderResultData(result.data!!)
     Log.d("debug", threadNetworkCredentials.networkName)
   } else {
     Log.d("debug", "User denied request.")
   }
 }

Jika Anda menyiapkan TBR baru, sebaiknya panggil preferredCredentials dan luncurkan Aktivitas. Panggilan ini akan memastikan bahwa TBR baru Anda akan menggunakan kredensial yang sama yang sudah disimpan sebagai pilihan di ponsel, sehingga mendorong konvergensi TBR yang berbeda ke jaringan yang sama.

private fun getPreferredThreadNetworkCredentials() {
  ThreadNetwork.getClient(this)
    .preferredCredentials
  .addOnSuccessListener { intentSenderResult ->
    intentSenderResult.intentSender?.let {
      preferredCredentialsLauncher.launch(IntentSenderRequest.Builder(it).build())
      } ?: Log.d("debug", "No preferred credentials found.")
    }
  .addOnFailureListener { e: Exception -> Log.d(TAG, "ERROR: [${e}]") }
}

Jika kasus penggunaan Anda terkait dengan penyiapan perangkat non-TBR, seperti perangkat akhir Matter-over-Thread baru, sebaiknya gunakan allActiveCredentials API untuk mengambil kredensial. Panggilan ini akan memindai TBR yang ditemukan di jaringan lokal dan dengan demikian tidak akan menampilkan kredensial yang tidak tersedia oleh TBR yang ada secara lokal.

// Creates the IntentSender result launcher for the getAllActiveCredentials API
private val getAllActiveCredentialsLauncher =
  registerForActivityResult(
    StartIntentSenderForResult()
  ) { result: ActivityResult ->
    if (result.resultCode == RESULT_OK) {
      val activeCredentials: List<ThreadNetworkCredentials> =