Membangun Aplikasi Contoh iOS

Aplikasi iOS contoh ini menggunakan Google Home API. Gunakan panduan ini untuk mem-build dan menjalankan aplikasi untuk pertama kalinya.

Prasyarat

Pastikan Anda memiliki persyaratan minimum untuk menggunakan Home API untuk iOS.

Untuk mem-build dan menginstal Aplikasi Contoh, Anda memerlukan komputer dengan Xcode versi 15.3+ yang terinstal di dalamnya.

Download Xcode

Untuk menguji aplikasi, Anda memerlukan:

  1. Akun Google.
  2. Apple ID yang terdaftar di Apple Developer Program untuk membuat file konfigurasi perangkat fisik. Jika belum dibuat, pendaftaran akan dikenai biaya tambahan dan mungkin memerlukan waktu hingga 48 jam untuk diselesaikan.
  3. Perangkat iOS (bukan simulator) yang menjalankan iOS 16.4+ yang disiapkan dengan akun pengujian.
  4. Jaringan Wi-Fi.
  5. Hub Google yang mendukung Home API.
  6. A Thread Border Router (TBR) jika perangkat Anda memerlukan Thread dan hub Anda tidak memiliki kemampuan tersebut.
  7. Setidaknya satu jenis perangkat yang didukung.

Untuk pengembangan, Anda memerlukan Mac yang memenuhi persyaratan berikut:

  • macOS Sonoma atau yang lebih baru
  • Xcode 15.3 atau yang lebih baru

Membuat file konfigurasi deployment Apple

Pertama, aplikasi memerlukan kemampuan App Attest diaktifkan. Oleh karena itu, aplikasi tidak dapat di-deploy ke perangkat simulator. Hal ini mengharuskan Anda membuat profil provisi dengan hak App Attest.

Kedua, aplikasi memerlukan Grup Aplikasi diaktifkan untuk komunikasi antara aplikasi dan MatterExtension. Hal ini mengharuskan Anda mendaftarkan ID grup aplikasi.

Untuk mengetahui detail selengkapnya, lihat Apple's Membuat profil provisi pengembangan di profil provisi.

Berikut ini garis besar langkah-langkah minimum yang diperlukan untuk men-deploy aplikasi:

  1. Buat ID grup aplikasi agar aplikasi Anda dapat berkomunikasi dengan MatterExtension.
    1. Login ke Apple Developer Portal.
    2. Tambahkan ID grup aplikasi. Misalnya, ID tersebut dapat diformat sebagai group.com.company.commissioning.
  2. Daftarkan perangkat pengujian Anda ke akun developer.

  3. Buat profil untuk target aplikasi Anda.

    1. Tentukan ID paket aplikasi untuk aplikasi Anda. ID harus unik dan deskriptif. Misalnya, ID tersebut dapat di format sebagai com.company.HomeApiSample. ID ini akan digunakan di seluruh bagian ini.
    2. Daftarkan ID Aplikasi Anda. Saat diminta, tambahkan kemampuan App Attest dan App Groups.

    3. Edit ID Aplikasi yang baru dibuat dan konfigurasi kemampuan App Groups untuk menambahkan ID grup aplikasi terdaftar.

    4. Buat profil provisi pengembangan untuk pengembangan aplikasi Anda. Kaitkan profil tersebut ke ID Aplikasi yang baru dibuat dan perangkat pengujian yang dipilih. Pastikan Anda memiliki sertifikat developer untuk menandatangani aplikasi.

  4. Buat profil untuk target MatterExtension Anda.

    1. Tentukan ID paket aplikasi untuk MatterExtension Anda. ID harus diwarisi dari ID aplikasi. Misalnya, ID tersebut dapat diformat sebagai com.company.HomeApiSample.MatterExtension.
    2. Daftarkan ID Aplikasi Anda. Saat diminta, tambahkan kemampuan App Group.
    3. Edit ID Aplikasi yang baru dibuat dan konfigurasi kemampuan App Groups untuk menambahkan ID grup aplikasi terdaftar yang dibuat pada langkah sebelumnya.
    4. Buat profil provisi pengembangan untuk MatterExtension.

Membuat client ID OAuth dan mengaktifkan Home API

Aplikasi Anda memerlukan client ID OAuth untuk mengidentifikasi dirinya ke backend autentikasi Google. Untuk iOS dan aplikasi, jenis aplikasi client ID OAuth harus dikonfigurasi sebagai iOS. Aplikasi juga akan melakukan panggilan ke Home API. Untuk mengaktifkan fungsi ini, API harus diaktifkan di project Google Cloud.

Membuat client ID OAuth

  1. Di konsol Google Cloud, buka dasbor pemilih project dan pilih project yang ingin Anda gunakan untuk membuat kredensial OAuth.
  2. Buka halaman API dan Layanan dengan mengklik tombol menu di sisi kiri atas > Lihat Semua Produk > API & Layanan.
  3. Di menu navigasi, klik Kredensial.

  4. Jika Anda belum mengonfigurasi layar izin untuk project Google Cloud ini, tombol Konfigurasi layar izin akan muncul. Dalam hal ini, konfigurasi layar izin Anda menggunakan prosedur berikut. Jika layar izin OAuth Anda telah dikonfigurasi dan status publikasinya adalah Pengujian, pastikan akun pengujian yang akan Anda gunakan ditambahkan ke grup Pengguna pengujian. Jika tidak, lanjutkan ke langkah berikutnya.

    1. Bergantung pada kasus penggunaan Anda, pilih Internal atau Eksternal, dan lalu klik Buat. Panel Layar izin OAuth akan ditampilkan.
    2. Masukkan informasi di halaman Informasi aplikasi sesuai dengan petunjuk di layar, lalu klik Simpan dan lanjutkan. Panel Cakupan akan ditampilkan.
    3. Anda tidak perlu menambahkan cakupan apa pun, jadi klik Simpan dan lanjutkan. Panel Pengguna pengujian akan ditampilkan.
    4. Jika Anda memilih untuk membuat layar izin internal, Anda harus menambahkan pengguna untuk menguji akses ke aplikasi Anda. Klik Tambahkan pengguna. Panel Tambahkan pengguna akan ditampilkan. Pengguna pengujian memiliki hak istimewa untuk memberikan izin di aplikasi Anda. Di kolom kosong, tambahkan satu atau beberapa alamat email Akun Google, lalu klik Tambahkan.
    5. Klik Simpan dan lanjutkan. Panel Ringkasan akan ditampilkan.
    6. Tinjau informasi layar izin OAuth Anda, lalu klik Kembali ke dasbor.

  5. Di panel menu sebelah kiri, klik Kredensial untuk membuat client ID OAuth Anda.

    Menyiapkan layar OAuth

    1. Klik tombol BUAT KREDENSIAL, lalu pilih client ID OAuth.
      1. Di bagian jenis aplikasi, pilih iOS.
    2. Masukkan ID Paket dengan ID aplikasi dan Apple Developer ID Tim. Kolom lainnya bersifat opsional dan dapat dibiarkan kosong.
    3. Klik BUAT, dan catat Client ID atau DOWNLOAD PLIST yang dibuat. ID ini akan digunakan nanti untuk mengaktifkan fungsi alur izin. Untuk mengetahui informasi selengkapnya, lihat bagian Membuat kredensial otorisasi

Mengaktifkan Home API

Aktifkan akses ke Home API.

  1. Di tab API dan Layanan, klik API &Layanan yang Diaktifkan.
  2. Klik AKTIFKAN API DAN LAYANAN di bagian atas halaman.
  3. Cari HOME API , lalu pilih.
  4. Di halaman detail Home API, klik AKTIFKAN.

Mendownload kode sumber

Kode sumber untuk Aplikasi Contoh tersedia di GitHub.

Buka tempat Anda ingin menyimpan project, lalu clone:

git clone https://github.com/google-home/google-home-api-sample-app-ios.git

Untuk memuat project di Xcode, klik File > Buka, lalu pilih GoogleHomeAPISampleIOS.xcodeproj di root repositori yang di-clone.

Menambahkan SDK ke project

Project Aplikasi Contoh memerlukan beberapa informasi tambahan agar dapat di-build. Hal ini mencakup penambahan file Framework SDK secara lokal, pengisian informasi ID akun developer, dan pengisian client ID OAuth Anda.

Mem-build aplikasi

Untuk mendownload Home API iOS SDK, Anda harus login ke Google Home Developers terlebih dahulu.

Login sekarang!

Konfigurasi project Xcode Anda untuk Aplikasi Contoh:

  1. Buka SDK yang didownload ke direktori ThirdParty/GoogleHomeSDK relatif terhadap direktori root project.
  2. Konfigurasi ID developer dan client ID OAuth:
    1. Di panel navigasi, cari folder GoogleHomeAPISampleIOS dan buka file Info.plist untuk diedit.

  3. Di file Info.plist, isi GIDClientID dengan client ID OAuth Anda (lihat bagian Menyiapkan izin OAuth), Nomor Project Cloud yang sesuai dengan project cloud Anda, dan GIDTeamID dengan ID Tim Apple Developer dari akun developer yang digunakan selama proses pendaftaran OAuth.

  4. Tambahkan Kemampuan App Attest:

    1. Di panel navigasi Xcode, pilih file project GoogleHomeAPISampleIOS untuk mengedit konfigurasi project.
    2. Klik tab Signing and Capabilities di bagian atas dan pilih target GoogleHomeAPISampleIOS di sisi kiri di bagian TARGETS.
    3. Tepat di bawah tab Signing and Capabilities, klik + Capability dan cari App Attest.
    4. Klik App Attest untuk menambahkan. Jika kemampuan ini tidak ada dalam penelusuran, project mungkin sudah menambahkannya.

  5. Tambahkan kemampuan App Groups.

    Menambahkan grup aplikasi

    1. Buka project GoogleHomeAPISampleIOS > target GoogleHomeAPISampleIOS.
    2. Klik Signing & Capabilities > + Capability.
    3. Pilih kemampuan App Groups.
    4. Klik ikon + di bagian App Groups dan tambahkan ID App Groups untuk aplikasi Anda yang ditambahkan di Portal Developer Apple.
    5. Ulangi langkah-langkah ini untuk target MatterAddDeviceExtension agar dapat ditambahkan ke App Groups.

  6. Perbarui ID Paket

    1. Agar berhasil menjalankan dan men-deploy Aplikasi Contoh di hardware menggunakan sertifikat developer dan profil provisi Anda, Anda harus memberikan ID paket yang unik. ID ini harus sama dengan ID yang terkait dengan kredensial klien OAuth Anda (lihat di atas).
    2. Di panel navigasi Xcode, pilih file project GoogleHomeAPISampleIOS untuk mengedit konfigurasi project.
    3. Klik tab Signing and Capabilities di bagian atas dan pilih target GoogleHomeAPISampleIOS di sisi kiri di bagian TARGETS.
    4. Pilih kolom ID Paket di bagian Signing dan masukkan ID unik untuk Aplikasi.
    5. Pilih atau instal profil provisi yang terkait dengan paket tersebut dengan hak yang diperlukan.
    6. Ulangi langkah-langkah ini untuk target MatterAddDeviceExtension guna memasukkan ID Paket untuk ekstensi dan mengimpor profil provisi terdaftarnya.

  7. Perbarui ID grup aplikasi terdaftar dalam kode.

    1. Aplikasi harus mengonfigurasi instance SDK untuk menggunakan ID Grup Aplikasi untuk fitur seperti commissioning perangkat. Perbarui aplikasi untuk menggunakan ID Grup Aplikasi yang terdaftar di Apple Developer Portal dengan menelusuri string HOME_API_TODO_ADD_APP_GROUP dan mengganti setiap instance dengan ID tersebut.

    Konfigurasi ini dilakukan dalam file berikut:

    • GoogleHomeAPISampleIOS.swift saat SDK diinisialisasi.
    • RequestHandler.swift
    • CommissioningManager.swift

  8. Konfigurasi cakupan OAuth di GoogleHomeAPISampleIOS.swift. Secara default, kode sumber Aplikasi Contoh menggunakan cakupan https://www.googleapis.com/auth/home.platform.v2. Banyak fitur di Aplikasi Contoh yang dibatasi oleh cakupan home.platform.v2 dan memerlukan persetujuan partner untuk mengaksesnya. Untuk menjalankan Aplikasi Contoh dengan cakupan https://www.googleapis.com/auth/home.platform.selected.devices standar, buka GoogleHomeAPISampleIOS.swift dan ubah homePlatformOAuthScope di Home.configure menjadi HomePlatformOAuthScope.v1:

    Home.configure {
  $0.sharedAppGroup = "HOME_API_TODO_ADD_APP_GROUP"
  $0.homePlatformOAuthScope = HomePlatformOAuthScope.v1
  ...
}