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 mengaktifkan dan mengontrol perangkat smart home dengan lancar.
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) serta mengontrol perangkat (misalnya, mengubah titik penyetelan termostat).
- Commissioning API: Mengonfigurasi (menyiapkan) perangkat Matter baru ke dalam fabric dengan upaya minimal.
- Automation API: Membuat, menghapus, dan membuat kueri otomatisasi yang berjalan di rumah pengguna.
Prasyarat
- Xcode versi stabil terbaru.
- Akun Google yang memiliki minimal satu struktur di rumah.
- Perangkat iOS yang menjalankan iOS 16.4+ yang disiapkan dengan akun pengujian.
- Apple ID yang terdaftar dalam Apple Developer Program untuk membuat profil penyediaan.
- Hub Google yang mendukung Home API.
Yang akan Anda pelajari
- Cara mem-build aplikasi iOS menggunakan 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.
- Cara menggunakan Automation API untuk membuat otomatisasi dasar.
2. Menyiapkan Rumah
Menyiapkan perangkat
Google Home Playground menawarkan berbagai perangkat smart home yang diemulasi dan di-build sebelumnya serta direkomendasikan untuk menjelajahi potensi penuh Home API, terutama jika Anda memiliki perangkat dalam jumlah terbatas di rumah.
Ikuti petunjuk untuk login ke Google Home Playground dan menyelesaikan penautan akun di aplikasi Google Home. Setelah menyelesaikannya, 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 pada kode ini 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 di seluruh codelab untuk menerapkan fungsi penuh. 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): Berada diGoogleHomeAPISampleIOS/Main/GoogleHomeAPISampleIOS.swift, ini adalah titik entri aplikasi utama. Class ini mengonfigurasi dan melakukan inisialisasi SDK serta menyiapkan antarmuka pengguna utama.Core Views (View/):MainView.swift: Tampilan root setelah peluncuran, yang berisiNavigationViewutama. Class 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: Mewakili 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 ruangan dan objekDeviceControldalam struktur yang dipilih.AutomationList.swift,AutomationViewModel.swift, dan sebagainya: Menangani pengambilan, tampilan, pembuatan, dan pengelolaan otomatisasi.
Device Controls (ViewModel/Device/):DeviceControl.swift: Class dasar untuk merepresentasikan perangkat yang dapat dikontrol di UI.- Subclass tertentu (
LightControl.swift,FanControl.swift,OnOffPlugInUnitControl.swift, dan sebagainya): Mengimplementasikan 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 commissioning perangkat Matter.
Utilities & UX (Utils/, UX/, Storage/): Berisi kode bantuan untuk elemen UI (warna, dimensi), penanganan error, penyimpanan data (SelectedStructureStorage.swift), dan utilitas lainnya.
Di seluruh codelab ini, Anda akan menemukan komentar seperti TODO atau blok kode dan pemberitahuan yang dikomentari dalam project start. Ini menandai bagian tempat Anda akan menambahkan atau menghapus komentar kode untuk menerapkan 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 Client ID OAuth dan mengaktifkan Home API, login terlebih dahulu ke Google Cloud, lalu buat project baru atau pilih project yang sudah ada. Kemudian, ikuti langkah-langkah yang diberikan untuk membuat Client ID 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.
Mem-build dan menjalankan project
Setelah mem-build dan menjalankan project dengan cabang start, dialog TODO dan layar yang menampilkan "Login Wajib" 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
Melakukan inisialisasi Home
Sebelum menggunakan Home API untuk iOS, Anda harus melakukan inisialisasi Home di aplikasi. 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 tidak tercantum dalam DeviceControlFactory, perangkat Anda akan ditampilkan sebagai "Tidak didukung". Untuk mempelajari lebih lanjut perangkat yang didukung, lihat halaman Jenis Perangkat yang Didukung di iOS.
Berinteraksi dengan perangkat
Steker outlet1 awalnya tidak aktif saat mengetuk atau menggeser perangkat. Untuk mengaktifkan interaksi dengannya, temukan GoogleHomeAPISampleIOS/ViewModel/Device/OnOffPlugInUnitControl.swift dan hapus komentar dan 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 pemberitahuan 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 ruangan baru dengan structure.createRoom(), buka pojok kiri atas dan pilih ikon"+" > Tambahkan Ruang. Masukkan nama ruang baru Anda, lalu klik "Buat Ruang". Ruang baru akan muncul setelah beberapa detik.
Memindahkan perangkat ke ruangan lain
Di GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, hapus komentar dan pemberitahuan 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 Ruang Lain", lalu pilih ruangan baru.
Menghapus ruang kosong
Di GoogleHomeAPISampleIOS/ViewModel/StructureViewModel.swift, hapus komentar dan pemberitahuan 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 yang kosong dengan structure.deleteRoom(), klik ikon sampah di sebelah kanan nama ruang, lalu konfirmasi tindakan tersebut. Perhatikan bahwa hanya ruang yang kosong yang dapat dihapus.
Catatan: Pindahkan perangkat kembali untuk membuat ruang kosong.
6. Commissioning
Catatan: Bagian ini memerlukan hub Google dan perangkat Matter. Pastikan hub Google dalam 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 dan Akun Google pengguna. Hal ini memberikan pengalaman penyiapan yang lancar langsung dalam aplikasi Anda.
Di GoogleHomeAPISampleIOS/Commissioning/CommissioningManager.swift, hapus komentar dan pemberitahuan 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. Aplikasi 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. Tindakan ini akan mencantumkan semua otomatisasi dalam struktur Anda dengan structure.listAutomations().
Catatan: Jika belum menyiapkan otomatisasi rumah, Anda akan melihat pesan "Tambahkan otomatisasi untuk memulai".
Membuat otomatisasi
Setelah Anda memahami Device API dan Structure API serta 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, lalu klik tombol "+ Tambahkan". Kemudian, pilih "Matikan lampu setelah 5 detik". Detail otomatisasi, termasuk starter, condition, dan action, akan muncul. Klik "Simpan" untuk membuat otomatisasi oleh structure.createAutomation().
Catatan: Otomatisasi yang tersedia bergantung pada perangkat di rumah Anda. Jika Anda tidak melihat otomatisasi yang tersedia, coba ganti nama perangkat lampu menjadi "light2".
Kembali ke tab "Perangkat" dan nyalakan lampu bernama "light2". Lampu akan otomatis mati 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 pemicu memenuhi persyaratan tertentu. Dalam hal ini, otomatisasi akan dijalankan 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.
8. Selamat
Selamat! Anda telah berhasil mem-build 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: Mengimplementasikan interaksi perangkat, seperti mengalihkan status
OnOffPluginUnitDeviceTypedengan memanggil perintah pada atributnya. - Pengelolaan Struktur: Menambahkan fungsi untuk membuat ruangan baru (
structure.createRoom()), memindahkan perangkat antarruangan (structure.move()), dan menghapus ruangan kosong (structure.deleteRoom()). - Komisi: Mengintegrasikan alur komisi SDK untuk menambahkan perangkat Matter baru (
MatterAddDeviceRequest). - Otomatisasi: Mempelajari cara membuat daftar, membuat (
structure.createAutomation()), dan menghapus (structure.deleteAutomation()) otomatisasi dalam struktur.
Sekarang Anda memiliki pemahaman dasar tentang cara memanfaatkan Home API untuk membuat 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 lanjut berbagai karakteristik dan perintah yang tersedia untuk berbagai perangkat.
- Lakukan eksperimen dengan membuat otomatisasi yang lebih kompleks menggunakan pemicu, kondisi, dan tindakan yang berbeda.
- Lihat dokumentasi Home API untuk mengetahui fitur dan detail lanjutan lainnya.
Bagus!