Membangun Aplikasi Contoh iOS

Contoh aplikasi iOS ini menggunakan Google Home API. Gunakan panduan ini untuk membangun 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 yang telah diinstal Xcode versi 15.3+.

Download Xcode

Untuk menguji aplikasi, Anda memerlukan:

  1. Akun Google.
  2. ID Apple 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. Thread Border Router (TBR) jika perangkat Anda memerlukan Thread dan hub Anda tidak memiliki kemampuan tersebut.
  7. Minimal 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 untuk diaktifkan. Akibatnya, library ini tidak dapat di-deploy ke perangkat simulator. Hal ini mengharuskan Anda membuat profil penyediaan dengan hak App Attest.

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

Untuk mengetahui detail selengkapnya, lihat Membuat profil penyediaan pengembangan Apple tentang profil penyediaan.

Berikut adalah 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 diformat 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 konfigurasikan kemampuan Grup Aplikasi untuk menambahkan ID grup aplikasi yang terdaftar.

    4. Buat profil penyediaan pengembangan untuk pengembangan aplikasi Anda. Kaitkan 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, formatnya dapat berupa com.company.HomeApiSample.MatterExtension.
    2. Daftarkan ID Aplikasi Anda. Saat diminta, tambahkan kemampuan App Group.
    3. Edit ID Aplikasi yang baru dibuat dan konfigurasikan kemampuan App Groups untuk menambahkan ID grup aplikasi terdaftar yang dibuat di langkah sebelumnya.
    4. Buat profil penyediaan 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 ini 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 APIs and Services dengan mengklik tombol menu di sisi kiri atas > View All Products > APIs & Services.
  3. Di menu navigasi, klik Credentials.

  4. Jika Anda belum mengonfigurasi layar izin untuk project Google Cloud ini, tombol Configure consent screen akan muncul. Jika demikian, konfigurasikan 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 External, lalu klik Create. Panel OAuth consent screen akan ditampilkan.
    2. Masukkan informasi di halaman informasi Aplikasi sesuai dengan petunjuk di layar, lalu klik Simpan dan lanjutkan. Panel Scopes akan ditampilkan.
    3. Anda tidak perlu menambahkan cakupan apa pun, jadi klik Save and continue. Panel Test users 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 Add users 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 Summary akan ditampilkan.
    6. Tinjau informasi layar izin OAuth Anda, lalu klik Back to dashboard.

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

    Menyiapkan layar OAuth

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

Mengaktifkan Home API

Mengaktifkan akses ke Home API.

  1. Di tab APIs and Services, klik Enabled APIs & Services.
  2. Klik ENABLE APIS AND SERVICES di bagian atas halaman.
  3. Telusuri HOME API, lalu pilih.
  4. Di halaman detail Home API, klik ENABLE.

Mendownload kode sumber

Kode sumber untuk Aplikasi Contoh tersedia di GitHub.

Buka tempat Anda ingin menyimpan project, lalu clone project tersebut:

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

Untuk memuat project di Xcode, klik File > Open, 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 termasuk menambahkan file Framework SDK secara lokal, mengisi informasi ID akun developer, dan mengisi client ID OAuth Anda.

Membangun aplikasi

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

Login sekarang!

Konfigurasikan project Xcode Anda untuk Aplikasi Contoh:

  1. Ekstrak SDK yang didownload ke direktori ThirdParty/GoogleHomeSDK yang terkait dengan direktori root project.
  2. Konfigurasikan ID Developer dan klien 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), Cloud Project Number yang sesuai dengan project cloud Anda, dan GIDTeamID dengan Apple Developer Team ID dari akun developer yang digunakan selama proses pendaftaran OAuth.

  4. Menambahkan 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, lalu pilih target GoogleHomeAPISampleIOS di sisi kiri di bagian TARGETS.
    3. Tepat di bawah tab Signing and Capabilities, klik + Capability dan telusuri App Attest.
    4. Klik App Attest untuk menambahkan. Jika kemampuan ini tidak ada dalam penelusuran, project mungkin telah 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 Grup Aplikasi untuk aplikasi Anda yang Anda tambahkan di Portal Developer Apple.
    5. Ulangi langkah-langkah ini untuk target MatterAddDeviceExtension guna menambahkannya ke App Groups.

  6. Memperbarui ID paket

    1. Agar berhasil menjalankan dan men-deploy Aplikasi Contoh di hardware menggunakan sertifikat developer dan profil penyediaan, 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, lalu 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 penyediaan 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 penyediaan terdaftarnya.

  7. Perbarui ID grup aplikasi yang terdaftar dalam kode.

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

    Konfigurasi ini dibuat dalam file berikut:

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

  8. Konfigurasikan 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 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
  ...
}