Membuat dan mengelola perangkat

Panduan ini membahas cara membuat, mengelola, dan menghapus perangkat. Pengelolaan perangkat yang tepat membantu menciptakan pengalaman pengguna yang lancar dan penggunaan Ambient API yang efisien.

Membuat Perangkat

Setelah pengguna berhasil melakukan autentikasi menggunakan alur OAuth 2.0 untuk Aplikasi TV dan Perangkat Input Terbatas, buat perangkat di akun Google Foto mereka.

Saat aplikasi Anda berhasil membuat perangkat menggunakan metode devices.create, Ambient API akan menampilkan objek AmbientDevice yang menyertakan id yang dihasilkan Google. Simpan id ini dengan aman dan kaitkan dengan pengguna Anda.

Penting: Simpan id. Jika Anda tidak menyimpan id yang dibuat Google, Anda tidak akan dapat mengambil atau mengelola perangkat nanti. Hal ini dapat menyebabkan perangkat tanpa induk di akun Google Foto pengguna Anda, yang tidak dapat diakses atau dibersihkan oleh aplikasi Anda.

Pembuatan Perangkat yang Efisien dengan OAuth

Ambient API menawarkan alur OAuth yang disederhanakan. Dengan meneruskan parameter state tambahan dalam permintaan OAuth awal dan memanggil devices.create dengan requestId yang cocok, Anda dapat menautkan proses pembuatan perangkat langsung ke alur login pengguna, sehingga menyederhanakan pengalaman pengguna dengan mengurangi jumlah kode QR yang perlu dipindai.

Untuk mengetahui detail dan contoh selengkapnya, lihat panduan Alur autentikasi yang disederhanakan untuk Ambient API.

Batas Perangkat

Aplikasi Anda dapat membuat hingga 100 perangkat per pengguna. Jika batas ini terlampaui, API akan menampilkan error RESOURCE_EXHAUSTED.

Mengelola Perangkat

Setelah perangkat dibuat dan ditautkan ke akun Google Foto pengguna, Anda mungkin perlu mengelola siklus prosesnya.

Mengambil Perangkat

Untuk mengambil informasi tentang perangkat tertentu, gunakan metode devices.get dengan id uniknya. Hal ini berguna untuk memeriksa status perangkat, seperti apakah mediaSourcesSet bernilai benar.

Memperbarui Perangkat

Anda dapat memperbarui properti tertentu dari perangkat yang ada, seperti nama tampilannya, menggunakan metode devices.patch. Hal ini memungkinkan pengguna mempersonalisasi perangkat mereka dan membuatnya lebih mudah diidentifikasi dalam Google Foto.

Catatan: Sebaiknya tawarkan kepada pengguna kesempatan untuk memberi nama perangkat mereka sebelum membuatnya. Hal ini akan memudahkan pengguna mengenali perangkatnya saat memilih item media di akun Google Foto mereka.

Hapus Perangkat

Terapkan strategi penghapusan perangkat untuk pembersihan yang tepat dan kontrol pengguna. Anda dapat menghapus perangkat menggunakan metode devices.delete.

Pertimbangkan skenario berikut untuk menghapus perangkat:

• Pembatalan hubungan pengguna: Jika pengguna membatalkan hubungan aplikasi Anda dari akun Google Foto miliknya, Anda harus menghapus perangkat yang sesuai.
• Perangkat Tanpa Pemilik: Jika Anda tidak dapat melacak id, tetapi masih memiliki requestId yang digunakan selama pembuatan, Anda dapat menggunakan requestId dengan devices.delete untuk menghapus perangkat tanpa pemilik. Tindakan ini membantu mencegah duplikat yang tidak disengaja dan menjaga akun pengguna tetap bersih.

Pertimbangan Penting dan Praktik Terbaik

• Siklus proses perangkat dan otorisasi pengguna: Anda harus mengelola siklus proses perangkat dan token otorisasi pengguna. Pertimbangkan berapa lama perangkat tetap aktif dan cara Anda menangani pembaruan token atau otorisasi ulang jika perangkat menjadi tidak aktif atau tokennya habis masa berlakunya.
• Penanganan Error: Terapkan penanganan error yang andal untuk semua panggilan API terkait perangkat. Bersiaplah untuk skenario seperti:
  • NOT_FOUND: Jika perangkat tidak ada atau tidak dimiliki oleh pengguna.
  • RESOURCE_EXHAUSTED: Jika Anda melampaui batas perangkat.
  • ALREADY_EXISTS: Jika Anda mencoba membuat perangkat dengan requestId yang sudah ada.

Langkah Berikutnya

• Aplikasi Contoh: Aplikasi contoh kami mencakup contoh pembuatan perangkat dan penggunaan data respons. Lihat fungsi createDevice untuk mengetahui info selengkapnya.
• Dokumentasi Referensi: Tinjau dokumen referensi tentang perangkat yang komprehensif untuk mendapatkan informasi mendetail tentang semua metode, parameter permintaan dan respons, serta kode error yang tersedia.
• Mencantumkan dan mengambil item media: Setelah membuat dan mengelola perangkat, pelajari cara mencantumkan dan mengambil item media untuk ditampilkan di perangkat tersebut.