1. Pengantar
Apa yang dimaksud dengan Home API?
Google Home API menyediakan serangkaian library bagi developer untuk memanfaatkan ekosistem Google Home. Dengan Home API, developer dapat membuat aplikasi yang dengan lancar melakukan commissioning dan mengontrol perangkat smart home.
Video ini memberikan panduan singkat tentang aplikasi seluler yang akan Anda buat, jadi ikuti video ini saat Anda mengerjakan codelab.
Komponen Home API
Home API terdiri dari:
- Device & Structure API: Berinteraksi dengan rumah pengguna. Aplikasi dapat menggunakan API ini untuk membaca info tentang perangkat, ruangan, dan struktur (misalnya, melihat suhu termostat saat ini) dan mengontrol perangkat (misalnya, mengubah titik penyetelan termostat).
- Commissioning API: Lakukan commissioning (penyiapan) perangkat Matter baru ke dalam fabric dengan upaya minimal.
- Automation API: Membuat, menghapus, dan membuat kueri otomatisasi yang berjalan di rumah pengguna.
Prasyarat
- Versi stabil Xcode terbaru.
- Akun Google yang memiliki setidaknya satu struktur di rumah.
- Perangkat iOS yang menjalankan iOS 16.4+ yang disiapkan dengan akun pengujian.
- Apple ID yang terdaftar dalam Program Developer Apple untuk membuat profil penyediaan.
- Hub Google yang mendukung Home API.
Yang akan Anda pelajari
- Cara membuat aplikasi iOS menggunakan Home API dengan praktik terbaik.
- Cara menggunakan Device and Structure API untuk merepresentasikan dan mengontrol smart home.
- Cara menggunakan Commissioning API untuk menambahkan perangkat ke ekosistem Google Home.
- Cara menggunakan Automation API untuk membuat otomatisasi dasar.
2. Menyiapkan Rumah Anda
Menyiapkan perangkat
Google Home Playground menawarkan berbagai perangkat smart home yang diemulasi dan telah dibuat sebelumnya, serta direkomendasikan untuk menjelajahi potensi penuh Home API, terutama jika Anda memiliki sejumlah perangkat terbatas di rumah.
Ikuti petunjuk untuk login ke Google Home Playground dan menyelesaikan penautan akun di aplikasi Google Home. Setelah menyelesaikan langkah ini, Anda akan dapat melihat perangkat di tab "Perangkat" di aplikasi Google Home.
3. Mempersiapkan
Mendapatkan kode aplikasi contoh
Mulai dengan meng-clone kode sumber dari GitHub:
git clone https://github.com/google-home/google-home-api-sample-app-ios.git
Direktori contoh berisi dua cabang, start dan finished, untuk codelab ini.
start: Kode awal untuk project ini, tempat Anda akan membuat perubahan untuk menyelesaikan codelab.finished: Kode yang sudah selesai untuk codelab ini, yang digunakan untuk memeriksa pekerjaan Anda.
Mempelajari kode 'start'
Mulai codelab ini dengan beralih ke cabang start dari repositori yang di-clone:
git checkout start
Cabang ini berisi kode awal untuk project. Anda akan mengubah kode ini selama codelab untuk menerapkan fungsi lengkap. Aplikasi contoh codelab menyediakan struktur dasar yang dibuat di Swift untuk berinteraksi dengan Home APIs iOS SDK. Mari kita lihat sekilas komponen utama dalam project start:
Main Entry (GoogleHomeAPISampleIOSApp): Terletak diGoogleHomeAPISampleIOS/Main/GoogleHomeAPISampleIOS.swift, ini adalah titik entri aplikasi utama. File ini mengonfigurasi dan menginisialisasi SDK serta menyiapkan antarmuka pengguna utama.Core Views (View/):MainView.swift: Tampilan root setelah peluncuran, yang berisiNavigationViewutama. Aplikasi ini menangani pemilihan struktur Google Home yang aktif dan menampilkanStructureViewyang sesuai.StructureView.swift: Menampilkan konten untuk struktur yang saat ini dipilih, menggunakan tab untuk beralih antara petak Perangkat dan daftar Otomatisasi. Aplikasi ini juga menyediakan menu untuk menambahkan ruangan atau perangkat.DeviceView.swift: Menampilkan kartu interaktif untuk satu perangkat dalam petakStructureView.AutomationsView.swift: Menampilkan daftar otomatisasi yang ada untuk struktur dan menyediakan navigasi untuk membuat atau melihat detail otomatisasi.
ViewModels (ViewModel/): Class ini mengelola status dan logika untuk tampilan.AccountViewModel.swift: Menangani koneksi ke objekHomedan mengelola status autentikasi.MainViewModel.swift: Mengelola daftar objekStructureyang tersedia dan melacak struktur yang dipilih.StructureViewModel.swift: Mengelola tampilan kamar dan objekDeviceControldalam struktur yang dipilih.AutomationList.swift,AutomationViewModel.swift, dan sebagainya: Menangani pengambilan, menampilkan, membuat, dan mengelola otomatisasi.
Device Controls (ViewModel/Device/):DeviceControl.swift: Class dasar untuk merepresentasikan perangkat yang dapat dikontrol di UI.- Subkelas tertentu (
LightControl.swift,FanControl.swift,OnOffPlugInUnitControl.swift, dan sebagainya): Menerapkan logika UI, kontrol perangkat, dan pemetaan status untuk berbagai jenis perangkat berdasarkan karakteristiknya. DeviceControlFactory.swift: Bertanggung jawab untuk membuat subclassDeviceControlyang sesuai untukHomeDevicetertentu.
Commissioning (Commissioning/):CommissioningManager.swift: Berisi logika untuk mengelola alur aktivasi perangkat Matter.
Utilities & UX (Utils/, UX/, Storage/): Berisi kode pembantu untuk elemen UI (warna, dimensi), penanganan error, penyimpanan data (SelectedStructureStorage.swift), dan utilitas lainnya.
Di sepanjang codelab ini, Anda akan menemukan komentar seperti TODO atau blok kode dan pemberitahuan yang dikomentari dalam project start. Bagian ini menandai tempat Anda akan menambahkan atau menghapus komentar kode untuk mengimplementasikan fungsi yang diperlukan, dengan mengikuti langkah-langkah yang diberikan.
Membuat file konfigurasi deployment Apple
Untuk mengonfigurasi App Attest, ikuti petunjuk tentang cara membuat file konfigurasi deployment Apple. Perhatikan bahwa setelah penyiapan, aplikasi hanya dapat di-deploy di perangkat sungguhan, bukan di simulator.
Menyiapkan autentikasi
Untuk mendapatkan ID Klien OAuth dan mengaktifkan Home API, pertama-tama login ke Google Cloud, lalu buat project baru atau pilih project yang sudah ada. Kemudian, ikuti langkah-langkah yang diberikan untuk membuat ID Klien OAuth dan mengaktifkan Home API serta menambahkan akun Anda ke daftar yang diizinkan.
Siapkan SDK
Dapatkan Home APIs iOS SDK dan konfigurasikan dengan melihat petunjuk penyiapan yang diberikan di Menyiapkan SDK. Jangan lupa untuk mengganti HOME_API_TODO_ADD_APP_GROUP dengan grup aplikasi Anda sendiri.
Membangun dan menjalankan project
Setelah membuat dan menjalankan project dengan cabang start, dialog TODO dan layar yang menampilkan "Sign in Required" akan muncul. Interaksi Home API akan diterapkan di bagian berikut.
Catatan: Temukan kode yang perlu diubah dengan menelusuri project untuk menemukan teks yang ditampilkan dalam dialog. Misalnya, telusuri "TODO: initialize Home".
4. Inisialisasi
Menginisialisasi Home
Sebelum menggunakan salah satu Home API untuk iOS, Anda harus melakukan inisialisasi Home di aplikasi Anda. Home adalah entri tingkat teratas ke SDK dan memberikan akses ke semua entitas dalam struktur pengguna. Saat meminta semua entity dari jenis tertentu, API akan menampilkan objek Query yang memungkinkan Anda memilih cara menerima hasilnya. Di GoogleHomeAPISampleIOS/Accounts/AccountViewModel.swift, hapus komentar dan pemberitahuan di connect() untuk menerapkan inisialisasi rumah.
/// TODO: initialize Home
/// Remove comments to initialize Home and handling permission.
private func connect() {
Task {
do {
self.home = try await Home.connect()
} catch {
Logger().error("Auth error: \(error).")
}
}
}
Izin untuk menggunakan Home API
Layar izin akan muncul saat Anda menjalankan aplikasi. Pilih struktur Google Home dan pilih akun yang ada di daftar yang diizinkan project Google Cloud Anda.
5. Perangkat dan Struktur
Mendapatkan ruangan dan perangkat
Di GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, hapus komentar dan pemberitahuan di getRoomsAndDevices() untuk mendapatkan ruangan dan perangkat dalam struktur yang dipilih dengan home.rooms() dan home.devices().
/// TODO: get rooms and devices
/// Remove comments to get the rooms and devices from home entry
private func getRoomsAndDevices(){
self.home.rooms().batched()
.combineLatest(self.home.devices().batched())
.receive(on: DispatchQueue.main)
.catch { error in
Logger().error("Failed to load rooms and devices: \(error)")
return Just((Set<Room>(), Set<HomeDevice>()))
}
.map { [weak self] rooms, devices in
guard let self = self else { return [] }
self.hasLoaded = true
return self.process(rooms: rooms, devices: devices)
}
/// receive from .map and .assign() to publisher entries
.assign(to: &self.$entries)
}
Fungsi process() pertama-tama memastikan perangkat berada di ruangan yang sama sebelum membuat perangkat berinteraksi sebagai HomeDevices menggunakan DeviceControl dan DeviceControlFactory.
Catatan: Jika perangkat Anda tidak tercantum di DeviceControlFactory, perangkat akan ditampilkan sebagai "Tidak Didukung". Untuk mempelajari lebih lanjut perangkat yang didukung, lihat halaman Jenis Perangkat yang Didukung di iOS.
Berinteraksi dengan perangkat
Awalnya, plugin outlet1 tidak aktif saat mengetuk atau menggeser di perangkat. Untuk mengaktifkan interaksi dengannya, cari GoogleHomeAPISampleIOS/ViewModel/Device/OnOffPlugInUnitControl.swift dan hapus komentar serta pemberitahuan dalam fungsi primaryAction().
/// TODO: primary action of OnOffPlug
/// Toggles the plug; usually provided as the `action` callback on a Button.
public override func primaryAction() {
self.updateTileInfo(isBusy: true)
Task { @MainActor [weak self] in
guard
let self = self,
let onOffPluginUnitDeviceType = self.onOffPluginUnitDeviceType,
let onOffTrait = onOffPluginUnitDeviceType.matterTraits.onOffTrait
else { return }
do {
try await onOffTrait.toggle()
} catch {
Logger().error("Failed to to toggle OnOffPluginUnit on/off trait: \(error)")
self.updateTileInfo(isBusy: false)
}
}
}
Fungsi primaryAction(), yang ditemukan dalam class OnOffPlugInUnitControl, mengalihkan status aktif/nonaktif steker smart atau perangkat apa pun yang direpresentasikan oleh OnOffPluginUnitDeviceType.
Contoh kontrol perangkat tambahan tersedia di GoogleHomeAPISampleIOS/ViewModel/Device.
Membuat ruangan baru
Structure API memungkinkan pembuatan dan penghapusan ruangan, serta transfer perangkat antar-ruangan.
Di GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, hapus komentar dan peringatan di addRoom().
/// TODO: add room
/// Add a new room in a given structure.
func addRoom(name: String, structure: Structure) {
Task {
do {
// The view will be updated with the values from the devices publisher.
_ = try await structure.createRoom(name: name)
} catch {
Logger().error("Failed to create room: \(error)")
}
}
}
Untuk membuat ruang baru dengan structure.createRoom(), buka pojok kiri atas dan pilih ikon"+" > Tambahkan Ruang. Masukkan nama ruang baru Anda, lalu klik "Buat Ruang". Ruangan baru akan muncul setelah beberapa detik.
Memindahkan perangkat ke ruangan lain
Di GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, hapus komentar dan peringatan di moveDevice().
/// TODO: move device
/// Move a device into a different room.
func moveDevice(device deviceID: String, to roomID: String, structure: Structure) {
Task {
do {
_ = try await structure.move(device: deviceID, to: roomID)
} catch {
Logger().error("Failed to move to room: \(error)")
}
}
}
Untuk memindahkan perangkat dengan structure.move(), tekan lama perangkat, pilih "Pindahkan ke Ruangan Lain", lalu pilih ruangan baru.
Menghapus ruang kosong
Di GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, hapus komentar dan peringatan di removeRoom().
/// TODO: delete room
/// Delete an empty room in a given structure.
func removeRoom(id: String, structure: Structure) {
Task {
do {
// The view will be updated with the values from the devices publisher.
_ = try await structure.deleteRoom(id: id)
} catch {
Logger().error("Failed to remove room: \(error)")
}
}
}
Untuk menghapus ruang kosong dengan structure.deleteRoom(), klik ikon sampah di sebelah kanan nama ruang, lalu konfirmasi tindakan. Perhatikan bahwa hanya ruang yang kosong yang dapat dihapus.
Catatan: Pindahkan perangkat kembali untuk membuat ruangan kosong.
6. Commissioning
Catatan: Bagian ini memerlukan hub Google dan perangkat Matter. Pastikan hub Google di struktur Anda online dan dapat dijangkau. Jika Anda tidak memiliki perangkat Matter, coba gunakan aplikasi Perangkat Virtual Matter.
Menambahkan perangkat Matter
Commissioning API memungkinkan aplikasi Anda menambahkan perangkat Matter baru ke rumah pengguna dan Akun Google. Hal ini memberikan pengalaman penyiapan yang lancar langsung di dalam aplikasi Anda.
Di GoogleHomeAPISampleIOS/Commissioning/CommissioningManager.swift, hapus komentar dan peringatan di addMatterDevice().
/// TODO: add Matter Device
/// Starts the Matter device commissioning flow to add the device to the user's home.
/// - Parameters:
/// - structure: The structure to add the device to.
/// - add3PFabricFirst: Whether to add the device to a third party fabric first.
public func addMatterDevice(to structure: Structure, add3PFabricFirst: Bool) {
self.isCommissioning = true
/// pass if it's 1p or 3p commissioning
let userDefaults = UserDefaults(
suiteName: CommissioningManager.appGroup)
userDefaults?.set(
add3PFabricFirst, forKey: CommissioningUserDefaultsKeys.shouldPerform3PFabricCommissioning)
Task {
do {
try await structure.prepareForMatterCommissioning()
} catch {
Logger().error("Failed to prepare for Matter Commissioning: \(error).")
self.isCommissioning = false
return
}
// Prepare the Matter request by providing the ecosystem name and home to be added to.
let topology = MatterAddDeviceRequest.Topology(
ecosystemName: "Google Home",
homes: [MatterAddDeviceRequest.Home(displayName: structure.name)]
)
let request = MatterAddDeviceRequest(topology: topology)
do {
Logger().info("Starting MatterAddDeviceRequest.")
try await request.perform()
Logger().info("Completed MatterAddDeviceRequest.")
let commissionedDeviceIDs = try structure.completeMatterCommissioning()
Logger().info("Commissioned device IDs: \(commissionedDeviceIDs).")
} catch let error {
structure.cancelMatterCommissioning()
Logger().error("Failed to complete MatterAddDeviceRequest: \(error).")
}
self.isCommissioning = false
}
}
Untuk membuat ruangan baru dengan structure.prepareForMatterCommissioning(), buka pojok kiri atas dan pilih ikon"+" > Tambahkan Perangkat ke Google Fabric. Fitur ini menggunakan MatterAddDeviceRequest untuk menambahkan perangkat Matter ke ruangan Anda. Setelah memilih ruangan dan nama perangkat, perangkat akan ditampilkan di layar "Perangkat".
7. Otomatisasi
Melihat semua otomatisasi dalam struktur
Ketuk Otomatisasi di menu navigasi bawah. Daftar ini akan mencantumkan semua otomatisasi dalam struktur Anda dengan structure.listAutomations().
Catatan: Jika Anda belum menyiapkan otomatisasi rumah, Anda akan melihat pesan "Tambahkan otomatisasi untuk memulai".
Membuat otomatisasi
Setelah Anda memahami Device dan Structure API serta cara menambahkan perangkat baru, sekarang saatnya membuat otomatisasi baru menggunakan Automation API.
Di GoogleHomeAPISampleIOS/ViewModel/Automation/AutomationsRepository.swift, hapus komentar, pemberitahuan, dan otomatisasi kosong di lightAutomation().
/// TODO: create automation
/// - Parameter devices: devices in current selected structure
/// - Returns: the automation object to be created
/// This automation will turn off the light after 5 seconds.
public func lightAutomation(devices: Set<HomeDevice>) async throws -> any DraftAutomation {
let light = devices.first { $0.name == "light2" }
guard let light else {
Logger().error("Unable to find light device with name light2")
throw HomeError.notFound("No devices support OnOffLightDeviceType")
}
return automation(
name: "Turn off light after 5 seconds",
description:
"""
Turns off light2 after it has been on for 5 seconds.
"""
) {
let onOffStarter = starter(light, OnOffLightDeviceType.self, OnOffTrait.self)
onOffStarter
condition {
onOffStarter.onOff.equals(true)
}
delay(for: Duration.seconds(5))
action(light, OnOffLightDeviceType.self) {
OnOffTrait.off()
}
}
}
Untuk membuat otomatisasi yang akan mematikan lampu lima detik setelah dinyalakan, buka tampilan otomatisasi dan klik tombol "+ Tambahkan". Kemudian, pilih "Matikan lampu setelah 5 detik". Detail otomatisasi, termasuk starter, condition, dan action, akan muncul. Klik "Simpan" untuk membuat otomatisasi menurut structure.createAutomation().
Catatan: Otomatisasi yang tersedia bergantung pada perangkat di rumah Anda. Jika Anda tidak melihat otomatisasi yang tersedia, coba ganti nama perangkat lampu Anda menjadi "light2".
Kembali ke tab "Perangkat" dan nyalakan lampu bernama "light2". Layar akan otomatis dinonaktifkan setelah lima detik.
Komponen otomatisasi adalah:
- Pemicu: Ini adalah peristiwa yang memulai otomatisasi. Dalam contoh ini, otomatisasi akan dimulai setelah ada perubahan pada
OnOffTrait. - Kondisi: Ini memeriksa apakah perangkat awal memenuhi persyaratan tertentu. Dalam hal ini, otomatisasi akan dieksekusi jika lampu menyala.
- Tindakan: Ini adalah otomatisasi yang ingin Anda lakukan, tetapi hanya jika pemicu memenuhi persyaratan. Jika kondisi terpenuhi, lampu akan dimatikan.
Untuk contoh tambahan, lihat halaman Contoh otomatisasi.
Menghapus otomatisasi
Metode structure.deleteAutomation() dipanggil saat Anda menggeser ke kiri pada otomatisasi yang ada dan mengetuk ikon sampah untuk menghapusnya dari struktur Anda.
8. Selamat
Selamat! Anda telah berhasil membuat aplikasi smart home dasar menggunakan Home API untuk iOS.
Yang Telah Anda Capai:
- Inisialisasi: Menghubungkan aplikasi Anda ke ekosistem Google Home menggunakan
Home.connect(). - Izin: Menangani autentikasi dan otorisasi pengguna untuk mengakses data rumah.
- Perangkat & Struktur: Mengambil dan menampilkan ruangan dan perangkat menggunakan
home.rooms()danhome.devices(). - Kontrol Perangkat: Menerapkan interaksi perangkat, seperti mengubah status
OnOffPluginUnitDeviceTypedengan memanggil perintah pada trait-nya. - Pengelolaan Struktur: Menambahkan fungsi untuk membuat ruangan baru (
structure.createRoom()), memindahkan perangkat antar-ruangan (structure.move()), dan menghapus ruangan kosong (structure.deleteRoom()). - Penyiapan: Mengintegrasikan alur penyiapan SDK untuk menambahkan perangkat Matter baru (
MatterAddDeviceRequest). - Otomatisasi: Menjelaskan cara mencantumkan, membuat (
structure.createAutomation()), dan menghapus (structure.deleteAutomation()) otomatisasi dalam struktur.
Sekarang Anda memiliki pemahaman dasar tentang cara memanfaatkan Home API untuk membangun pengalaman kontrol smart home yang kaya di iOS.
Langkah Berikutnya:
- Pelajari cara mengontrol jenis perangkat lain yang disediakan di aplikasi contoh (lampu, kipas, tirai, dan sebagainya).
- Pelajari lebih dalam berbagai sifat dan perintah yang tersedia untuk berbagai perangkat.
- Lakukan eksperimen dengan membuat otomatisasi yang lebih kompleks menggunakan berbagai pemicu, kondisi, dan tindakan.
- Lihat dokumentasi Home API untuk mengetahui fitur dan detail yang lebih canggih.
Bagus!