Mulai Menggunakan Ambient API

Ambient API memungkinkan aplikasi Anda menghubungkan perangkat standby ke akun Google Foto pengguna dan menampilkan foto yang dipilih.

Alur Ambient API

Berikut adalah perincian cara kerja Ambient API untuk menghubungkan perangkat, lalu mengambil dan menampilkan item media:

  1. Periksa perangkat yang ada (direkomendasikan): Sebelum membuat perangkat baru, sebaiknya periksa apakah perangkat untuk pengguna saat ini sudah ada. Aplikasi Anda harus mempertahankan pemetaan antara pengguna internal dan deviceId yang disediakan Google untuk perangkat apa pun yang mereka buat melalui aplikasi Anda. Jika deviceId ditemukan untuk pengguna, Anda dapat melanjutkan untuk memuat ulang token otorisasi mereka (jika diperlukan).

  2. Memulai otorisasi OAuth 2.0 (dan secara opsional membuat perangkat): Mulai alur OAuth 2.0 untuk TV dan Perangkat Input Terbatas dengan meminta kode otorisasi.

  3. Membuat perangkat baru: Aplikasi Anda membuat perangkat di akun Google Foto pengguna dengan memanggil CreateDevice dan memberikan UUID v4 yang valid.

    Setelah pembuatan perangkat berhasil, API akan menampilkan objek AmbientDevice yang berisi deviceId yang ditetapkan Google. Aplikasi Anda harus menyimpan deviceId ini dan mengaitkannya dengan pengguna.

  4. Menampilkan settingsUri: objek AmbientDevice menyertakan settingsUri. Tampilkan URI ini kepada pengguna, biasanya sebagai kode QR, yang dapat dipindai pengguna menggunakan perangkat seluler mereka. URI ini mengarahkan pengguna ke aplikasi Google Foto tempat mereka dapat mengonfigurasi sumber media (misalnya, album) yang ingin ditampilkan di perangkat standby.

  5. Melakukan polling untuk mediaSourcesSet: Aplikasi Anda harus memanggil metode GetDevice secara berkala, yang menyediakan deviceId, untuk memeriksa status perangkat standby. Pantau kolom mediaSourcesSet dalam respons AmbientDevice. Awalnya, nilainya akan salah.

    Setelah pengguna berhasil memilih sumber media di aplikasi Google Foto, kolom ini akan berubah menjadi benar.

    Respons AmbientDevice menyertakan pollingConfig dengan pollInterval yang harus Anda gunakan sebagai panduan untuk frekuensi polling.

  6. Mengambil item media: Jika mediaSourcesSet menampilkan true, aplikasi Anda dapat mulai mengambil item media yang dipilih oleh pengguna.

    Panggil metode ListMediaItems, yang menyediakan deviceId. API akan menampilkan ListMediaItemsResponse yang berisi daftar objek AmbientMediaItem. Setiap AmbientMediaItem menyertakan detail seperti objek id, createTime, dan MediaFile dengan metadata tambahan. MediaFile berisi baseUrl yang dapat Anda gunakan untuk mengambil byte item media yang sebenarnya. Tinjau panduan untuk Mencantumkan dan mengambil item media untuk mengetahui detail tentang parameter baseUrl tambahan.

  7. Menampilkan Item Media: Gunakan baseUrl dari MediaFile untuk mendownload dan menampilkan konten media di perangkat standby.

Pertimbangan Penting

Batasan dan pengelolaan perangkat:

  • Batas perangkat: Perhatikan batas 100 perangkat per pengguna aplikasi Anda.
  • Aktivitas dan token perangkat: 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 token berakhir masa berlakunya.

Panduan untuk Membuat dan mengelola perangkat memiliki detail tambahan.

Menggunakan item media:

  • Penggunaan item media: Pahami cara mengambil dan menangani konten item media dengan benar menggunakan baseUrl, termasuk autentikasi atau parameter yang diperlukan.
  • Penanganan error: Terapkan penanganan error yang andal untuk panggilan API, termasuk skenario seperti NOT_FOUND untuk perangkat, FAILED_PRECONDITION jika sumber media tidak ditetapkan, dan RESOURCE_EXHAUSTED jika batas perangkat tercapai.

Panduan untuk Mencantumkan dan mengambil item media memiliki detail tambahan.

Langkah Berikutnya