Mengonfigurasi aplikasi Anda untuk Ambient API

Untuk mulai menggunakan Ambient API, konfigurasikan project Anda dengan mengaktifkan API di Konsol API Google dan menyiapkan client ID OAuth 2.0. Ambient API menggunakan OAuth 2.0 untuk Aplikasi TV dan Perangkat Input Terbatas.

Aplikasi Anda berinteraksi dengan Ambient API atas nama pengguna Ambient API. Pengguna mengizinkan permintaan API ini menggunakan protokol OAuth 2.0.

Client ID OAuth 2.0 memungkinkan pengguna aplikasi Anda login, mengautentikasi, dan menggunakan Ambient API. Ambient API tidak mendukung akun layanan; untuk menggunakan API ini, pengguna harus login ke Akun Google yang valid.

Mengonfigurasi aplikasi Anda

Aktifkan API terlebih dahulu, lalu minta client ID OAuth 2.0.

Mengaktifkan API

Sebelum dapat menggunakan Ambient API, Anda harus mengaktifkannya di project Anda.

Buka Konsol Google API.
Dari menu bar, pilih project atau buat project baru.
Untuk membuka salah satu Google Photos API, dari menu Navigation, pilih APIs & Services > Library.
Telusuri "Ambient API". Pilih Ambient API, lalu klik Enable.

Meminta client ID OAuth 2.0

Ikuti langkah-langkah berikut untuk meminta client ID OAuth dan mengonfigurasinya untuk aplikasi Anda. Ambient API menggunakan OAuth 2.0 untuk Aplikasi TV dan Perangkat Input Terbatas.

Buka Konsol API Google, lalu pilih project Anda.
Dari menu, pilih APIs & Services > Credentials.
Di halaman Credentials, klik Create Credentials > OAuth client ID.

Catatan: Jika menyiapkan project baru, Anda mungkin diminta untuk mengonfigurasi layar izin project.
Pilih Jenis aplikasi Anda. Dalam contoh ini, jenis aplikasinya adalah TV dan Perangkat Input Terbatas.
Berikan nama untuk klien OAuth 2.0 Anda, lalu klik Create.
Dari dialog klien OAuth yang dihasilkan, salin hal berikut:
- ID Klien
- Rahasia klien

Aplikasi Anda dapat mengakses Google API yang diaktifkan menggunakan nilai ini.

Sebelum dapat meluncurkan aplikasi publik yang mengakses Ambient API, aplikasi Anda harus ditinjau oleh Google. Pesan "Aplikasi tidak terverifikasi" akan muncul di layar saat Anda menguji aplikasi, hingga diverifikasi.

Setelah mengonfigurasi aplikasi, Anda siap untuk memulai. Anda dapat menjelajahi referensi berikut, atau membaca tentang alur autentikasi yang disederhanakan untuk Ambient API.

Mengubah client ID

Resource yang dibuat melalui Google Photos API hanya dapat diakses atau diubah menggunakan client ID asli yang digunakan untuk membuatnya. Misalnya, jika Anda membuat session di Picker API dengan client ID tertentu, lalu mengubah client ID tersebut di aplikasi, aplikasi Anda akan kehilangan akses ke resource API apa pun yang dibuat dengan client ID sebelumnya.

Rencanakan dengan cermat dan pilih jenis client ID yang benar untuk Photos API yang Anda gunakan. Hanya ubah client ID Anda jika benar-benar diperlukan untuk menghindari masalah akses.

Alur autentikasi yang disederhanakan untuk Ambient API

Alur autentikasi Ambient API standar mengharuskan pengguna memindai 2 kode QR:

Yang pertama kali login ke Akun Google-nya (jika belum login ke Akun Google-nya).
Yang kedua, yang ditautkan ke perangkat Ambient yang baru dibuat di akun Google Foto mereka, tempat mereka dapat memilih item media untuk ditampilkan.

Alur yang disederhanakan memungkinkan Anda memberikan satu kode QR kepada pengguna dengan meneruskan parameter state tambahan dengan panggilan autentikasi awal Anda.

Saat meminta kode perangkat dan pengguna sebagai bagian dari OAuth untuk perangkat input terbatas, sertakan parameter state tambahan dengan permintaan Anda. Tambahkan kode berikut ke parameter state:

Parameter

Parameter
`requestId`	`string` Wajib. ID unik yang disediakan klien untuk permintaan ini. Hal ini digunakan untuk mengurangi duplikasi resource jika terjadi kegagalan jaringan. ID ini harus memiliki format string UUID (versi 4) dan mengikuti persyaratan berikut: Tidak boleh berisi informasi identitas sensitif apa pun tentang pengguna. Harus berisi 32 karakter heksadesimal yang dibagi menjadi lima grup yang dipisahkan dengan tanda hubung, dalam format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (atau 8-4-4-4-12).
`displayName`	`string` Opsional. Nama tampilan yang ditentukan pengguna untuk perangkat ini. Ini akan terlihat oleh pengguna dari setelan aplikasi Google Foto, tetapi hanya dapat diedit melalui API ini. Nama tampilan yang valid harus memiliki antara 1 dan 100 karakter (inklusif).

requestId

string

Wajib. ID unik yang disediakan klien untuk permintaan ini. Hal ini digunakan untuk mengurangi duplikasi resource jika terjadi kegagalan jaringan.

ID ini harus memiliki format string UUID (versi 4) dan mengikuti persyaratan berikut:

Tidak boleh berisi informasi identitas sensitif apa pun tentang pengguna.
Harus berisi 32 karakter heksadesimal yang dibagi menjadi lima grup yang dipisahkan dengan tanda hubung, dalam format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (atau 8-4-4-4-12).

displayName

string

Opsional. Nama tampilan yang ditentukan pengguna untuk perangkat ini.

Ini akan terlihat oleh pengguna dari setelan aplikasi Google Foto, tetapi hanya dapat diedit melalui API ini.

Nama tampilan yang valid harus memiliki antara 1 dan 100 karakter (inklusif).

Misalnya, lihat blok kode berikut:

    const response = await fetch("https://oauth2.googleapis.com/device/code", {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            client_id: config.clientId,
            scope: "profile https://www.googleapis.com/auth/photosambient.mediaitems",
            state: JSON.stringify({
                'requestId': requestId,
                'displayName': "My Device"
            })
        })
    });

Respons yang berhasil akan menyertakan user_code dan verification_url, yang Anda tampilkan kepada pengguna (kemungkinan besar sebagai kode QR) sehingga mereka dapat membukanya di perangkat terpisah. Dengan menyertakan parameter state, saat nanti Anda memanggil createDevice dengan Ambient API, Anda dapat melewati presentasi settingsUri dalam kode QR kedua, karena langkah terakhir dalam alur OAuth akan otomatis mengarahkan ke lokasi ini.

Untuk mengetahui detail lengkapnya, kami telah menyertakan penjelasan yang lebih menyeluruh. Anda juga dapat meninjau kode di aplikasi contoh kami, untuk mengetahui contoh penggunaan parameter state sebagai bagian dari OAuth untuk perangkat input terbatas dengan Ambient API.

Detail tentang alur autentikasi yang disederhanakan

Untuk sepenuhnya memahami alur OAuth yang disederhanakan untuk Ambient API, sebaiknya pahami alur OAuth 2.0 untuk TV dan Aplikasi Perangkat Input Terbatas serta alur Ambient API standar. Berikut adalah langkah-langkah untuk setiap alur.

OAuth 2.0 untuk Aplikasi TV dan Perangkat Input Terbatas:

Aplikasi Anda mengirimkan permintaan ke server otorisasi Google yang mengidentifikasi cakupan yang akan diminta izinnya oleh aplikasi Anda untuk diakses.
Server merespons dengan beberapa informasi yang digunakan dalam langkah berikutnya, seperti kode perangkat dan kode pengguna.
Anda menampilkan informasi yang dapat dimasukkan pengguna di perangkat terpisah untuk memberi otorisasi pada aplikasi Anda.
Aplikasi Anda mulai melakukan polling pada server otorisasi Google untuk menentukan apakah pengguna telah memberikan otorisasi ke aplikasi Anda.
Pengguna beralih ke perangkat dengan kemampuan input yang lebih kaya, meluncurkan browser web, membuka URL yang ditampilkan di langkah 3, dan memasukkan kode yang juga ditampilkan di langkah 3. Kemudian, pengguna dapat memberikan (atau menolak) akses ke aplikasi Anda.
Respons berikutnya untuk permintaan polling Anda berisi token yang diperlukan aplikasi Anda untuk memberikan otorisasi permintaan atas nama pengguna. (Jika pengguna menolak akses ke aplikasi Anda, respons tidak akan berisi token.)

Alur Ambient API:

Periksa token OAuth yang ada, lalu muat ulang token atau minta token baru.
Setelah mendapatkan token OAuth, buat perangkat baru.
Tampilkan settingsUri kepada pengguna, dan mulai polling perangkat hingga mediaSourcesSet menampilkan nilai benar.
Pengguna membuka settingsUri dan memilih foto yang ingin dibagikan ke aplikasi Anda.
Setelah mediaSourcesSet menampilkan true, ambil daftar mediaItems.
Sekarang Anda dapat memulai slideshow atau pengalaman standby lainnya.

Kedua alur tersebut menyertakan langkah saat Anda menampilkan URL kepada pengguna, dan pengguna membukanya di perangkat input yang lebih kaya. Dengan menyertakan parameter state dalam panggilan OAuth awal, Anda dapat menghindari URL kedua yang harus ditampilkan.

Hal ini berfungsi karena langkah terakhir alur OAuth 2.0 untuk TV dan Aplikasi Perangkat Input Terbatas biasanya mengalihkan pengguna ke halaman yang bertuliskan "Anda sekarang dapat kembali ke perangkat Anda". Dengan menyertakan parameter status, langkah terakhir alur kini akan mencoba mengalihkan Anda ke settingsUri. Aplikasi Anda akan masih menerima token OAuth. Anda harus menggunakan token ini untuk memanggil createDevice menggunakan requestId yang sama. Setelah perangkat dengan ID yang sama dibuat, alur OAuth awal akan berhasil mengalihkan pengguna Anda ke halaman yang benar di perangkat kaya dalam aplikasi Foto.

Ingat poin-poin berikut:

Sebaiknya tetap tampilkan settingsUri jika ada masalah dengan autentikasi.
Anda tetap dapat menggunakan settingsUri dalam kasus lain, seperti saat pengguna ingin memperbarui pilihan foto mereka.