The Home APIs Developer Challenge is ON! Show us your skills for a chance to win exciting prizes.

Halaman ini diterjemahkan oleh Cloud Translation API.

Mem-build aplikasi seluler menggunakan Home API di Android

1. Sebelum memulai

Google Home API menyediakan serangkaian library bagi developer Android untuk memanfaatkan ekosistem Google Home. Dengan API baru ini, developer dapat membuat aplikasi yang mengaktifkan dan mengontrol perangkat smart home dengan lancar.

Google menyediakan Aplikasi Contoh Android untuk developer yang ingin mengakses contoh yang berfungsi menggunakan Google Home API. Codelab ini didasarkan pada cabang Aplikasi Contoh yang memandu Anda cara menggunakan Permissions, Commissioning, Device, dan Structure API.

Prasyarat

Pengetahuan tentang ekosistem Google Home (Cloud-to-cloud dan Matter).
Workstation dengan Android Studio (Ladybug 2024.3.1 atau yang lebih baru) terinstal.
Ponsel Android yang memenuhi persyaratan Home API (lihat Prasyarat) dengan Layanan Google Play dan Aplikasi Google Home terinstal.
Google Home Hub yang kompatibel dan mendukung Google Home API.
Opsional - Perangkat smart home yang kompatibel dengan Google Home API.

Yang akan Anda pelajari

Cara mem-build aplikasi Android menggunakan Google Home API dengan praktik terbaik.
Cara menggunakan Device API dan Structure API untuk merepresentasikan dan mengontrol smart home.
Cara menggunakan Commissioning API untuk menambahkan perangkat ke ekosistem Google Home.

Opsional: Menyiapkan Rumah

Sebelum menggunakan Google Home API, Anda harus menyiapkan rumah di Akun Google menggunakan aplikasi Google Home, dan menambahkan beberapa perangkat. Bagian ini membahas cara melakukannya menggunakan Google Home Playground, yang menyediakan perangkat smart home virtual.

Buka home-playground.withgoogle.com di browser web Anda, login dengan Akun Google Anda, lalu lihat apakah perangkat yang diemulasi berikut muncul:

outlet1: Steker Aktif/Nonaktif
light2: Lampu yang dapat diredupkan
light3: Lampu Nyala/Mati
ac3: AC
blinds4: Penutup Jendela
washer5: Mesin cuci smart

Buka aplikasi Google Home di perangkat seluler, ketuk tombol Tambahkan, lalu pilih Kompatibel dengan Google Home. Telusuri "playground" dalam daftar, lalu pilih project "Google Home Playground", dan ketuk Lanjutkan.

Google Home Playground akan menampilkan halaman otorisasi akun. Ketuk Otorisasi atau Login dengan Google. Anda akan melihat semua perangkat yang dikonfigurasi dari aplikasi web di aplikasi seluler.

Pilih semua perangkat dan selesaikan proses penyiapan. Kembali ke halaman Beranda, Anda akan melihat semua perangkat yang tersedia.

Perangkat yang didukung dalam daftar kini tersedia untuk digunakan dengan Google Home API.

2. Menyiapkan project

Diagram berikut mengilustrasikan arsitektur aplikasi Home API:

Arsitektur Home API untuk aplikasi Android

Kode Aplikasi: Kode inti yang dikerjakan developer untuk mem-build antarmuka pengguna aplikasi dan logika untuk berinteraksi dengan Home APIs SDK.
Home APIs SDK: Home APIs SDK yang disediakan oleh Google berfungsi dengan Layanan Home APIs di GMSCore untuk mengontrol perangkat smart home. Developer mem-build aplikasi yang berfungsi dengan Home API dengan memaketkannya dengan Home API SDK.
GMSCore di Android: GMSCore, yang juga dikenal sebagai layanan Google Play, adalah platform Google yang menyediakan layanan sistem inti, yang memungkinkan fungsi utama di semua perangkat Android bersertifikasi. Modul layar utama layanan Google Play berisi layanan yang berinteraksi dengan Home API.

Menyiapkan Home SDK

Ikuti langkah-langkah yang diuraikan di Menyiapkan SDK untuk mendapatkan SDK terbaru.

Mendapatkan Aplikasi Contoh

Kode sumber untuk Aplikasi Contoh tersedia di GitHub. Codelab ini menggunakan contoh dari cabang codelab-branch-1 Aplikasi Contoh.

Buka tempat Anda ingin menyimpan project dan clone cabang codelab-branch-1:

$ git clone -b codelab-branch-1 https://github.com/google-home/google-home-api-sample-app-android.git

Mem-build Aplikasi Contoh

Lakukan langkah 1-5 di Mem-build aplikasi.

Jika aplikasi berhasil berjalan di ponsel, Anda akan melihat halaman utama Aplikasi Contoh. Namun, Anda tidak akan dapat login hingga menyiapkan autentikasi OAuth dan menerapkan bagian yang hilang menggunakan Permission API.

3. Menyiapkan Authentication

Home API menggunakan OAuth 2.0 untuk memberikan akses ke perangkat dalam struktur. OAuth memungkinkan pengguna memberikan izin ke aplikasi atau layanan tanpa harus mengekspos kredensial login mereka.

Ikuti petunjuk di Menyiapkan izin OAuth untuk mengonfigurasi layar izin. Pastikan untuk membuat minimal satu akun pengujian.

Kemudian, ikuti petunjuk di Menyiapkan kredensial OAuth untuk membuat kredensial aplikasi.

4. Izin Penanganan dan Inisialisasi

Di bagian ini, Anda akan mempelajari cara menginisialisasi SDK dan menangani izin pengguna dengan melengkapi bagian yang hilang menggunakan Permissions API.

Menentukan Jenis dan Ciri yang Didukung

Saat mengembangkan aplikasi, Anda harus secara eksplisit mencatat jenis dan karakteristik perangkat yang akan didukung aplikasi. Di Aplikasi Contoh, kita melakukannya dengan menentukan daftar statis dalam objek pendamping di HomeApp.kt, yang kemudian dapat direferensikan di seluruh aplikasi sesuai kebutuhan:

companion object {

  // List of supported device types by this app:
  val supportedTypes: List<DeviceTypeFactory<out DeviceType>> = listOf(
    OnOffLightDevice,
    DimmableLightDevice,

  // ...
  )
  // List of supported device traits by this app:
  val supportedTraits: List<TraitFactory<out Trait>> = listOf(
  OnOff,
  LevelControl,
  // ...
  )
}

Lihat Jenis perangkat yang didukung dan Indeks Ciri di Android untuk melihat semua jenis dan ciri perangkat yang didukung.

Hapus tanda komentar Langkah 4.1.1 dan 4.1.2 di file sumber HomeApp.kt untuk mengaktifkan kode sumber yang meminta izin.

companion object {
// List of supported device types by this app:
val supportedTypes: List<DeviceTypeFactory<out DeviceType>> = listOf(
// TODO: 4.1.1 - Non-registered device types will be unsupported
//             ContactSensorDevice,
//             ColorTemperatureLightDevice,
//             DimmableLightDevice,
//             ExtendedColorLightDevice,
//             GenericSwitchDevice,
//             GoogleDisplayDevice,
//             GoogleTVDevice,
//             OccupancySensorDevice,
//             OnOffLightDevice,
//             OnOffLightSwitchDevice,
//             OnOffPluginUnitDevice,
//             OnOffSensorDevice,
//             RootNodeDevice,
//             SpeakerDevice,
//             ThermostatDevice,
)
// List of supported device traits by this app:
val supportedTraits: List<TraitFactory<out Trait>> = listOf(
// TODO: 4.1.2 - Non-registered traits will be unsupported
//             AreaAttendanceState,
//             AreaPresenceState,
//             Assistant,
//             AssistantBroadcast,
//             AssistantFulfillment,
//             BasicInformation,
//             BooleanState,
//             OccupancySensing,
//             OnOff,
//             Notification,
//             LevelControl,
//             TemperatureControl,
//             TemperatureMeasurement,
//             Thermostat,
//             Time,
//             Volume,
        )
}

Melakukan inisialisasi Objek HomeClient

Semua aplikasi yang menggunakan Home API melakukan inisialisasi objek HomeClient, yang merupakan antarmuka utama untuk berinteraksi dengan API. Kita menyiapkan objek ini di penginisialisasi class HomeApp (HomeApp.kt).

// Registry to record device types and traits used in this app:
val registry = FactoryRegistry(
  types = supportedTypes,
  traits = supportedTraits
)
// Configuration options for the HomeClient:
val config = HomeConfig(
  coroutineContext = Dispatchers.IO,
  factoryRegistry = registry
)
// Initialize the HomeClient, which is the primary object to use all Home APIs:
homeClient = Home.getClient(context = context, homeConfig = config)

Pertama, kita membuat FactoryRegistry menggunakan jenis dan karakteristik yang didukung yang telah kita tentukan sebelumnya. Kemudian, menggunakan registry ini, kita melakukan inisialisasi HomeConfig, yang berisi konfigurasi yang diperlukan untuk menjalankan API. Selanjutnya, kita menggunakan panggilan Home.getClient(...) untuk mendapatkan instance HomeClient.

Semua interaksi kita dengan Home API akan dilakukan melalui objek HomeClient ini.

Menggunakan Permissions API

Autentikasi pengguna untuk Home API dilakukan melalui Permissions API. File sumber PermissionsManager.kt Aplikasi Contoh berisi kode untuk autentikasi pengguna. Hapus komentar konten fungsi checkPermissions(...) dan requestPermissions(...) untuk mengaktifkan izin Aplikasi Contoh.

Mendaftar:

homeClient.registerActivityResultCallerForPermissions(activity)

Meluncurkan:

try {
    val result: PermissionsResult
    result = homeClient.requestPermissions(forceLaunch = true)
    when (result.status) {
        PermissionsResultStatus.SUCCESS -> // Success Case
        PermissionsResultStatus.CANCELLED -> // User Cancelled
        PermissionsResultStatus.ERROR -> // Some Error
else -> // Unsupported Case
    }
}
catch (e: HomeException) { ... }

Memeriksa:

try {
    val state: PermissionsState
    state = homeClient.hasPermissions().first { state ->
        state != PermissionsState.PERMISSIONS_STATE_UNINITIALIZED
    }
    when (state) {
        PermissionsState.GRANTED -> // Signed In
        PermissionsState.NOT_GRANTED -> // Not Signed In
        PermissionsState.PERMISSIONS_STATE_UNAVAILABLE -> // ...
        PermissionsState.PERMISSIONS_STATE_UNINITIALIZED -> // ...
else -> // Unsupported case
    }
}
catch (e: HomeException) { ... }

       homeClient.hasPermissions().collect( { state ->
// Track the changes on state
        } )

Hapus tanda komentar Langkah 4.3.1 di PermissionsManager.kt untuk mengaktifkan kode yang meminta izin:

fun requestPermissions() {
    scope.launch {
    try {
// TODO: 4.3.1 - Request the permissions from the Permissions API
//                 // Request permissions from the Permissions API and record the result:
//                 val result: PermissionsResult = client.requestPermissions(forceLaunch = true)
//                 // Adjust the sign-in status according to permission result:
//                 if (result.status == PermissionsResultStatus.SUCCESS)
//                     isSignedIn.emit(true)
//                 // Report the permission result:
//                 reportPermissionResult(result)
    }
    catch (e: HomeException) { MainActivity.showError(this, e.message.toString()) }
    }
}

Sekarang, jalankan aplikasi di ponsel Anda, ikuti langkah-langkahnya, dan izinkan izin. Anda akan melihat alur berikut:

Pesan "Memuat" tidak pernah hilang, tetapi ini karena kita belum menerapkan kode yang membaca struktur dan perangkat. Kita akan melakukannya di bagian berikutnya.

5. Memahami model data

Di Home API, Model Data terdiri dari:

Structure mewakili rumah yang berisi ruangan dan perangkat.
Room adalah bagian dari struktur dan berisi perangkat.
Perangkat (ditentukan sebagai HomeDevice) dapat ditetapkan ke struktur (atau rumah) atau ruangan dalam struktur.
Perangkat terdiri dari satu atau beberapa instance DeviceType.
DeviceType terdiri dari instance Trait.
Trait terdiri dari instance Attribute (untuk membaca/menulis), instance Command (untuk mengontrol atribut), dan instance Event (untuk membaca atau berlangganan data perubahan sebelumnya).
Instance Automation adalah bagian dari struktur dan menggunakan metadata serta perangkat rumah untuk mengotomatiskan tugas di rumah.

Di bagian ini, Anda akan mempelajari cara mengembangkan kode sumber untuk menunjukkan cara menggunakan API struktur untuk mengurai dan merender struktur rumah, ruangan, perangkat, dan sebagainya.

Membaca struktur

Desain Home API didasarkan pada Flow Kotlin untuk melakukan streaming objek model data (misalnya, Structure, HomeDevice, dan sebagainya). Developer berlangganan Flow untuk mendapatkan semua objek yang terdapat dalam objek (misalnya, Structure, Room, dan sebagainya).

Untuk mengambil semua struktur, panggil fungsi structures(), yang menampilkan alur struktur. Kemudian, panggil fungsi daftar pada alur untuk mendapatkan semua struktur yang dimiliki pengguna.

// Get the a snapshot of all structures from the current homeClient
val allStructures : Set<Structure> =
    homeClient.structures()   // HomeObjectsFlow<Structure>
    .list()                   // Set<Structure>

Panduan arsitektur aplikasi sangat merekomendasikan untuk mengadopsi pendekatan pemrograman Reaktif modern guna meningkatkan aliran data dan pengelolaan status aplikasi.

Berikut cara Aplikasi Contoh mematuhi gaya coding Reaktif:

Model tampilan (seperti StructureViewModel dan DeviceViewModel, sebagai holder status) berlangganan alur dari Home APIs SDK untuk menerima perubahan nilai, dan mempertahankan status terbaru.
View (seperti StructureView dan DeviceView) berlangganan model tampilan untuk menerima status dan merender UI agar mencerminkan perubahan tersebut.
Saat pengguna mengklik tombol pada tampilan (misalnya, tombol "On" pada perangkat lampu), peristiwa akan memicu fungsi model tampilan, yang memanggil fungsi Home API yang merespons (misalnya, perintah On dari sifat OnOff).

Pada Langkah 5.1.1 di HomeAppViewModel.kt, kita berlangganan peristiwa perubahan struktur dengan memanggil fungsi collect(). Hapus komentar pada bagian yang menelusuri structureSet yang ditampilkan oleh respons Structures API dan dikirimkan di StructureViewModel's StateFlow. Hal ini memungkinkan aplikasi memantau perubahan status struktur:

   private suspend fun subscribeToStructures() {
// TODO: 5.1.1 - Subscribe the structure data changes
// // Subscribe to structures returned by the Structures API:
// homeApp.homeClient.structures().collect { structureSet ->
//     val structureVMList: MutableList<StructureViewModel> = mutableListOf()
//     // Store structures in container ViewModels:
//     for (structure in structureSet) {
//         structureVMList.add(StructureViewModel(structure))
//     }
//     // Store the ViewModels:
//     structureVMs.emit(structureVMList)
//
//     // If a structure isn't selected yet, select the first structure from the list:
//     if (selectedStructureVM.value == null && structureVMList.isNotEmpty())
//         selectedStructureVM.emit(structureVMList.first())
//
// }
}

Di DevicesView.kt, aplikasi berlangganan StructureViewModel'sStateFlow, yang memicu rekomposisi UI saat data struktur berubah. Hapus komentar kode sumber di Langkah 5.1.2 untuk merender daftar struktur sebagai menu drop-down:

   val structureVMs: List<StructureViewModel> = homeAppVM.structureVMs.collectAsState().value
...
DropdownMenu(expanded = expanded, onDismissRequest = { expanded = false }) {
// TODO: 5.1.2 - Show list of structures in DropdownMenu
//  for (structure in structureVMs) {
//      DropdownMenuItem(
//          text = { Text(structure.name) },
//          onClick = {
//              scope.launch { homeAppVM.selectedStructureVM.emit(structure) }
//              expanded = false
//          }
//      )
//  }
}
...

Jalankan kembali aplikasi. Anda akan melihat menu saat mengetuk panah:

Mengurai Struktur

Langkah berikutnya adalah menjelajahi objek rumah dalam struktur. Ambil ruangan dari struktur:

val rooms: Set<Room>
rooms = structure.rooms().list()

Kemudian, Anda dapat menjelajahi ruangan untuk mengambil perangkat:

val devices: Set<HomeDevice>
devices = room.devices().list()

Penting: Dalam model data Home API, struktur dapat berisi perangkat yang tidak ditetapkan ke ruangan, jadi pastikan untuk mengambil perangkat tanpa ruangan di aplikasi Anda juga:

val devicesWithoutRooms: MutableSet<HomeDevice> = mutableSetOf()

for (device in structure.devices().list())
if (!device.isInRoom)
  devicesWithoutRooms.add(device)

Sekali lagi, dalam kode contoh yang ada, kita berlangganan alur untuk mendapatkan daftar Ruang dan Perangkat terbaru. Periksa kode pada Langkah 5.2.1 dan 5.2.2 di file sumber StructureViewModel.kt dan hapus tanda komentarnya untuk mengaktifkan langganan data ruangan:

val roomVMs : MutableStateFlow<List<RoomViewModel>>
val deviceVMs : MutableStateFlow<List<DeviceViewModel>>
val deviceVMsWithoutRooms : MutableStateFlow<List<DeviceViewModel>>
private suspend fun subscribeToRooms() {
// TODO: 5.2.1 - Subscribe the room data changes
//   // Subscribe to changes on rooms:
//   structure.rooms().collect { roomSet ->
//       val roomVMs = mutableListOf<RoomViewModel>()
//       // Store rooms in container ViewModels:
//       for (room in roomSet) {
//           roomVMs.add(RoomViewModel(room))
//       }
//       // Store the ViewModels:
//       this.roomVMs.emit(roomVMs)
//   }
}
private suspend fun subscribeToDevices() {
// TODO: 5.2.2 - Subscribe the device data changes in a structure
//   // Subscribe to changes on devices:
//   structure.devices().collect { deviceSet ->
//       val deviceVMs = mutableListOf<DeviceViewModel>()
//       val deviceWithoutRoomVMs = mutableListOf<DeviceViewModel>()
//       // Store devices in container ViewModels:
//       for (device in deviceSet) {
//           val deviceVM = DeviceViewModel(device)
//           deviceVMs.add(deviceVM)
//           // For any device that's not in a room, additionally keep track of a separate list:
//           if (!device.isInRoom)
//               deviceWithoutRoomVMs.add(deviceVM)
//       }
//       // Store the ViewModels:
//       this.deviceVMs.emit(deviceVMs)
//       deviceVMsWithoutRooms.emit(deviceWithoutRoomVMs)
//   }
    }

Hapus komentar Langkah 5.2.3 dan 5.2.4 di file sumber DevicesView.kt untuk merender daftar kamar sebagai menu:

val selectedRoomVMs: List<RoomViewModel> =
selectedStructureVM.roomVMs.collectAsState().value
...
for (roomVM in selectedRoomVMs) {
// TODO: 5.2.3 - Render the list of rooms
//   RoomListItem(roomVM)
// TODO: 5.2.4 - Render the list of devices in a room
//   val deviceVMsInRoom: List<DeviceViewModel> = roomVM.deviceVMs.collectAsState().value
//
//   for (deviceVM in deviceVMsInRoom) {
//       DeviceListItem(deviceVM, homeAppVM)
//   }
}

Setelah Anda memiliki perangkat, kita akan mempelajari cara menggunakannya.

6. Menggunakan Perangkat

Home API menggunakan objek HomeDevice untuk mengambil perangkat dan kemampuannya. Developer dapat berlangganan atribut perangkat dan menggunakannya untuk merepresentasikan perangkat smart home di aplikasi mereka.

Membaca status perangkat

Objek HomeDevice menampilkan kumpulan nilai statis, seperti nama perangkat atau status konektivitas. Sebagai developer, Anda dapat mengambilnya segera setelah mendapatkan perangkat dari API:

val id: String = device.id.id
val name: String = device.name
val connectivity: ConnectivityState =
    device.sourceConnectivity.connectivityState

Untuk mendapatkan kemampuan perangkat, Anda perlu mengambil jenis dan karakteristik dari HomeDevice. Untuk melakukannya, Anda dapat berlangganan alur jenis perangkat sebagai berikut, dan mengambil karakteristik dari jenis perangkat:

device.types().collect { typeSet ->
var primaryType : DeviceType = UnknownDeviceType()
for (typeInSet in typeSet)
if (typeInSet.metadata.isPrimaryType)
                    primaryType = typeInSet
            val traits: List<Trait> = mutableListOf()
for (trait in primaryType.traits())
if (trait.factory in myTraits)
                    traits.add(trait)
for (trait in traits)
                parseTrait(trait, primaryType)
        }

Setiap perangkat berisi kumpulan DeviceType (kemampuan yang dipaketkan) yang didukung, yang dapat Anda ambil menggunakan device.types(). Jenis perangkat ini berisi karakteristik yang dapat diambil menggunakan type.traits(). Setiap perangkat menandai salah satu jenisnya sebagai jenis utama (yang dapat diperiksa menggunakan type.metadata.isPrimaryType) yang harus Anda tampilkan di aplikasi. Untuk memberikan pengalaman yang lengkap kepada pengguna, sebaiknya jelajahi semua jenis yang ditampilkan dan integrasikan semua karakteristik yang tersedia untuk Anda.

Setelah mengambil atribut, Anda dapat mengurainya menggunakan fungsi seperti berikut untuk menafsirkan nilai:

fun <T : Trait?> parseTrait(trait : T, type: DeviceType) {
    val status : String = when (trait) {
        is OnOff -> { if (trait.onOff) "On" else "Off" }
        is LevelControl -> { trait.currentLevel.toString() }
        is BooleanState -> {
            when (type.factory) {
                ContactSensorDevice -> {
if (trait.stateValue) "Closed"
else "Open"
                }
else -> ...
            }
        }
else -> ...
    }
}

Perhatikan bahwa dapat ada variasi dalam hal yang diwakili oleh suatu karakteristik, bergantung pada jenis perangkat yang menampilkannya (lihat BooleanState dalam contoh sebelumnya), sehingga Anda perlu mengetahui konteks setiap jenis perangkat untuk memahami apa yang sebenarnya diwakili oleh karakteristiknya.

Hapus komentar Langkah 6.1.1 dan 6.1.2 dalam file sumber DeviceViewModel.kt untuk mengambil status:

private suspend fun subscribeToType() {
// Subscribe to changes on device type, and the traits/attributes within:
device.types().collect { typeSet ->
// Container for the primary type for this device:
var primaryType : DeviceType = UnknownDeviceType()
...
// TODO: 6.1.1 - Determine the primary type for this device
//       // Among all the types returned for this device, find the primary one:
//       for (typeInSet in typeSet)
//           if (typeInSet.metadata.isPrimaryType)
//               primaryType = typeInSet
//
//       // Optional: For devices with a single type that did not define a primary:
//       if (primaryType is UnknownDeviceType && typeSet.size == 1)
//           primaryType = typeSet.first()
// Container for list of supported traits present on the primary device type:
val supportedTraits: List<Trait> = getSupportedTraits(primaryType.traits())
...
}
fun getSupportedTraits(traits: Set<Trait>) : List<Trait> {
           val supportedTraits: MutableList<Trait> = mutableListOf()
// TODO: 6.1.2 - Get only the supported traits for this device
//   for (trait in traits)
//       if (trait.factory in HomeApp.supportedTraits)
//           supportedTraits.add(trait)
return supportedTraits
}

Hapus komentar Langkah 6.1.3 di DeviceView.kt untuk merender atribut OnOff, termasuk nama dan statusnya, sebagai String:

Box (Modifier.padding(horizontal = 24.dp, vertical = 8.dp)) {
when (trait) {
is OnOff -> {
// TODO: 6.1.3 - Render controls based on the trait type
// Column (Modifier.fillMaxWidth()) {
//     Text(trait.factory.toString(), fontSize = 20.sp)
//     Text(DeviceViewModel.getTraitStatus(trait, type), fontSize = 16.sp)
// }
...
}
is LevelControl -> {
      ...
  }
   is BooleanState -> {
      ...
  }
   is OccupancySensing -> {
      ...
  }
  ...
}

Jika Anda menjalankan aplikasi sekarang dengan jenis perangkat yang didukung (misalnya perangkat Lampu), aplikasi akan menampilkan status terbaru untuk semua perangkat.

Memberikan perintah perangkat

Untuk memberikan perintah ke perangkat, Home API menyediakan fungsi praktis pada objek Trait seperti trait.on() atau trait.moveToLevel(...):

fun <T : Trait?> issueCommand(trait : T) {
     when (trait) {
         is OnOff -> {
// trait.on()
// trait.off()
   }
   is LevelControl -> {
// trait.moveToLevel(...)
// trait.moveToLevelWithOnOff(...)
        }
    }
}

Tips: Setelah menentukan jenis sifat, gunakan fitur pelengkapan otomatis Android Studio untuk melihat jenis tindakan yang tersedia untuk berinteraksi dengan sifat tersebut.

Hapus komentar Langkah 6.2.1 di DeviceView.kt untuk menambahkan kontrol fungsional di aplikasi:

Box (Modifier.padding(horizontal = 24.dp, vertical = 8.dp)) {
when (trait) {
is OnOff -> {
                ....
// TODO: 6.2.1 - Render controls based on the trait type
//   Switch (checked = (trait.onOff == true), modifier = Modifier.align(Alignment.CenterEnd),
//       onCheckedChange = { state ->
//           scope.launch { if (state) trait.on() else trait.off() }
//       },
//       enabled = isConnected
//   )
}

Jika Anda menjalankan aplikasi sekarang, Anda akan dapat mengontrol perangkat fisik di dunia nyata.

Jika Anda mengetuk kontrol OnOff pada bohlam, perangkat akan menyala.

Untuk informasi selengkapnya tentang cara mengontrol perangkat, lihat Mengontrol perangkat di Android.

7. Mengonfigurasi perangkat

Commissioning API memungkinkan developer menambahkan perangkat ke ekosistem Google Home, dan menyediakannya untuk dikontrol menggunakan Home API. Hanya perangkat Matter yang didukung. Di bagian ini, kita akan mempelajari cara mengaktifkan commissioning perangkat di aplikasi Anda.

Sebelum memulai bagian ini, pastikan prasyarat berikut terpenuhi:

Google Hub yang mendukung Matter yang berada di jaringan yang sama dengan ponsel Android Anda telah ditambahkan ke aplikasi Google Home.
Anda telah membuat project developer di Konsol Developer Google Home dengan VID 0xFFF1 dan PID 0x8000.

Jika memiliki perangkat Matter fisik dengan kode QR untuk commissioning, Anda dapat langsung melanjutkan ke Mengaktifkan commissioning API. Jika tidak, lanjutkan ke bagian berikutnya, tempat kami membahas cara menggunakan aplikasi Matter Virtual Device (MVD) untuk membuat perangkat virtual yang dapat menerima komisi.

Opsional: Menyiapkan perangkat Matter yang dapat dikomisi

Cara termudah untuk menyiapkan perangkat Matter yang dapat dikomisi adalah menggunakan perangkat yang diemulasi yang disediakan oleh aplikasi Perangkat Virtual Matter (MVD).

Setelah menginstal MVD dan menyiapkan firewall, jalankan MVD:

Buat perangkat OnOff. Perhatikan bahwa project ini belum dikomisi - Anda akan mengonfigurasinya nanti di codelab ini.

Mengaktifkan Commissioning API

Commissioning API berfungsi di luar Aktivitas aplikasi, sehingga commissioning perlu ditangani secara berbeda dari Home API lainnya. Untuk menyiapkan aplikasi guna melakukan commissioning, Anda memerlukan dua variabel.

Satu variabel adalah ActivityResultLauncher, yang digunakan untuk mengirim intent komisi dan mengelola callback hasil. Variabel lainnya adalah CommissioningResult, yang merupakan objek yang digunakan untuk menyimpan hasil commissioning. Lihat contoh berikut untuk mengetahui cara menyiapkan commissioning:

var launcher: ActivityResultLauncher<IntentSenderRequest>
lateinit var commissioningResult: CommissioningResult?
launcher = activity.registerForActivityResult(StartIntentSenderForResult()) { result ->
try {
  commissioningResult = CommissioningResult.fromIntentSenderResult(
      result.resultCode, result.data)
  } catch (exception: ApiException) {
// Catch any issues
 }
}

Setelah alur komisi disiapkan, Anda akan mem-build intent komisi, dan meluncurkannya menggunakan peluncur yang kita buat di contoh sebelumnya. Sebaiknya tempatkan intent dan peluncur dalam fungsi khusus seperti berikut. Fungsi khusus dapat dikaitkan dengan elemen UI (seperti tombol +Tambahkan Perangkat) dan dipanggil berdasarkan permintaan pengguna:

fun requestCommissioning() {
// Retrieve the onboarding payload used when commissioning devices:
val payload = activity.intent?.getStringExtra(Matter.EXTRA_ONBOARDING_PAYLOAD)
  scope.launch {
    // Create a commissioning request to store the device in Google's Fabric:
    val request = CommissioningRequest.builder()
      .setStoreToGoogleFabric(true)
      .setOnboardingPayload(payload)
      .build()
    // Initialize client and sender for commissioning intent:
    val client: CommissioningClient = Matter.getCommissioningClient(context)
    val sender: IntentSender = client.commissionDevice(request).await()
    // Launch the commissioning intent on the launcher:
    launcher.launch(IntentSenderRequest.Builder(sender).build())
  }
}

Hapus komentar Langkah 7.1.1 di CommissioningManager.kt untuk mengaktifkan kemampuan komisioning dan membuat tombol +Add Device berfungsi di Aplikasi Contoh.

// Called by +Add Device button in DeviceView.kt
fun requestCommissioning() {
// Retrieve the onboarding payload used when commissioning devices:
val payload = activity.intent?.getStringExtra(Matter.EXTRA_ONBOARDING_PAYLOAD)
// TODO: 7.1.1 - Launch the commissioning intent
// scope.launch {
//     // Create a commissioning request to store the device in Google's Fabric:
//     val request = CommissioningRequest.builder()
//         .setStoreToGoogleFabric(true)
//         .setOnboardingPayload(payload)
//         .build()
//     // Initialize client and sender for commissioning intent:
//     val client: CommissioningClient = Matter.getCommissioningClient(context)
//     val sender: IntentSender = client.commissionDevice(request).await()
//     // Launch the commissioning intent on the launcher:
//     launcher.launch(IntentSenderRequest.Builder(sender).build())
// }
}

Menjalankan fungsi ini akan memulai Alur Komisi, yang akan menampilkan layar yang menyerupai screenshot berikut:

Memahami alur Komisi

Alur commissioning mencakup serangkaian layar yang memandu pengguna menambahkan perangkat ke Akun Google mereka:

Pengguna akan disambut dengan pemindai kode QR yang dapat mereka gunakan untuk memindai kode QR dari perangkat Matter. Selanjutnya, alur akan menampilkan Perjanjian Pengguna, penemuan dan komisi perangkat, serta memberi nama perangkat. Setelah selesai, alur akan mengubah fokus kembali ke aplikasi, dan meneruskan hasil komisi dalam fungsi callback yang kita buat drafnya di bagian sebelumnya.

Salah satu manfaat Commissioning API adalah alur UX ditangani oleh SDK, sehingga developer dapat menyiapkan dan menjalankannya dengan sangat cepat. Hal ini juga memberi pengguna pengalaman yang konsisten saat menambahkan perangkat di berbagai aplikasi.

Untuk mengetahui lebih lanjut commissioning API, buka Commissioning API di Android.

8. Selamat!

Selamat! Anda telah berhasil membuat aplikasi Android menggunakan Google Home API. Di seluruh codelab ini, Anda telah mempelajari Izin, Perangkat, Struktur, dan Komisi API. Dalam codelab berikutnya, Membuat otomatisasi lanjutan menggunakan Home API di Codelab Android, kita akan mempelajari Automation API dan Discovery API, serta menyelesaikan aplikasi.

Semoga Anda menikmati pembuatan aplikasi yang mengontrol perangkat secara kreatif dalam ekosistem Google Home.

Langkah berikutnya

Lanjutkan ke bagian berikutnya dalam perjalanan Anda mempelajari Home API di Android dengan menyelesaikan codelab kedua dalam seri ini: Membuat otomatisasi lanjutan menggunakan Home API di Android.
Anda dapat menghubungi kami untuk memberikan rekomendasi, atau melaporkan masalah melalui Issue Tracker, topik dukungan Smart Home.