Dokumen ini menjelaskan cara aplikasi mendapatkan otorisasi untuk membuat permintaan ke Tag Manager API.
Memberi Otorisasi Permintaan
Sebelum pengguna dapat melihat informasi akun mereka di situs Google mana pun, mereka harus login terlebih dahulu dengan Akun Google. Dengan cara yang sama, saat pengguna pertama kali mengakses aplikasi Anda, mereka perlu mengizinkan aplikasi Anda untuk mengakses data mereka.
Setiap permintaan yang dikirim aplikasi Anda ke Tag Manager API harus menyertakan token otorisasi. Token ini juga mengidentifikasi aplikasi Anda ke Google.
Tentang protokol otorisasi
Aplikasi Anda harus menggunakan OAuth 2.0 untuk mengizinkan permintaan. Tidak ada protokol otorisasi lain yang didukung. Jika aplikasi Anda menggunakan Login dengan Google, beberapa aspek otorisasi akan ditangani untuk Anda.
Mengizinkan permintaan dengan OAuth 2.0
Semua permintaan ke Tag Manager API harus diizinkan oleh pengguna terautentikasi.
Detail proses otorisasi, atau "alur", untuk OAuth 2.0 bervariasi bergantung pada jenis aplikasi yang Anda tulis. Proses umum berikut berlaku untuk semua jenis aplikasi:
- Saat membuat aplikasi, Anda mendaftarkannya menggunakan Konsol Google API. Selanjutnya, Google menyediakan informasi yang akan Anda perlukan nanti, seperti ID klien dan rahasia klien.
- Aktifkan Tag Manager API di Konsol Google API. (Jika API tidak tercantum di Konsol API, lewati langkah ini.)
- Saat memerlukan akses ke data pengguna, aplikasi Anda akan meminta cakupan akses tertentu kepada Google.
- Google menampilkan layar izin kepada pengguna, yang meminta mereka mengizinkan aplikasi Anda untuk meminta beberapa data.
- Jika pengguna menyetujui, Google akan memberikan token akses berumur singkat ke aplikasi Anda.
- Aplikasi Anda meminta data pengguna, dengan menambahkan token akses ke permintaan.
- Jika Google menentukan bahwa permintaan Anda dan token tersebut valid, data yang diminta akan ditampilkan.
Beberapa alur mencakup langkah tambahan, seperti penggunaan token refresh untuk memperoleh token akses baru. Informasi selengkapnya tentang alur untuk berbagai jenis aplikasi dapat dilihat di dokumentasi OAuth 2.0 Google.
Berikut informasi cakupan OAuth 2.0 untuk Tag Manager API:
| Cakupan | Arti |
|---|---|
https://www.googleapis.com/auth/tagmanager.readonly |
Melihat penampung Google Tag Manager. |
https://www.googleapis.com/auth/tagmanager.edit.containers |
Mengelola penampung Google Tag Manager. |
https://www.googleapis.com/auth/tagmanager.delete.containers |
Hapus penampung Google Tag Manager. |
https://www.googleapis.com/auth/tagmanager.edit.containerversions |
Mengelola versi penampung Google Tag Manager. |
https://www.googleapis.com/auth/tagmanager.publish |
Publikasikan penampung Google Tag Manager Anda. |
https://www.googleapis.com/auth/tagmanager.manage.users |
Mengelola izin pengguna data Google Tag Manager Anda. |
https://www.googleapis.com/auth/tagmanager.manage.accounts |
Mengelola akun Google Tag Manager Anda. |
Untuk meminta akses menggunakan OAuth 2.0, aplikasi Anda memerlukan informasi cakupan, serta informasi yang disediakan oleh Google saat Anda mendaftarkan aplikasi (seperti ID klien dan rahasia klien).
Memulai
Untuk mulai menggunakan Tag Manager API, pertama-tama Anda harus menggunakan alat penyiapan, yang memandu Anda menyelesaikan pembuatan project di Konsol Google API dan mengaktifkan API.
Untuk menyiapkan akun layanan baru, lakukan hal berikut:
- Klik Create credentials > Service account key.
- Pilih apakah akan mendownload kunci publik/pribadi akun layanan sebagai file P12 standar, atau sebagai file JSON yang dapat dimuat oleh library klien Google API.
Pasangan kunci umum/pribadi baru Anda dibuat atau didownload ke komputer Anda, dan berfungsi sebagai satu-satunya salinan untuk kunci ini. Anda bertanggung jawab untuk menyimpannya dengan aman.
Alur OAuth 2.0 Umum
Panduan berikut menguraikan kasus penggunaan umum untuk alur OAuth 2.0 tertentu:
Server Web
Alur ini cocok untuk akses otomatis/offline/terjadwal ke akun Google Tag Manager pengguna.
- Memperbarui informasi Tag Manager secara otomatis dari server.
Sisi klien
Ideal saat pengguna berinteraksi langsung dengan aplikasi untuk mengakses Akun Google Tag Manager mereka dalam browser. Alur ini menghilangkan kebutuhan akan kemampuan sisi server, tetapi juga membuatnya tidak praktis untuk pelaporan otomatis/offline/terjadwal.
- Alat konfigurasi berbasis browser yang disesuaikan.
Aplikasi Terinstal
Untuk aplikasi yang didistribusikan sebagai paket dan diinstal oleh pengguna. Alur ini mengharuskan aplikasi atau pengguna memiliki akses ke browser untuk menyelesaikan alur autentikasi.
- Widget desktop di PC atau Mac.
- Plugin untuk sistem pengelolaan konten. Manfaat alur ini dibandingkan dengan server web atau sisi klien adalah satu project Konsol API dapat digunakan untuk aplikasi Anda. Hal ini memungkinkan penginstalan yang lebih sederhana bagi pengguna.
Akun Layanan
Berguna untuk akses otomatis/offline/terjadwal ke akun Google Tag Manager Anda sendiri. Misalnya, untuk membuat alat kustom guna memantau akun Google Tag Manager Anda sendiri dan membagikannya kepada pengguna lain.
Pemecahan masalah
Jika access_token Anda telah habis masa berlakunya atau Anda menggunakan cakupan yang salah
untuk panggilan API tertentu, Anda akan mendapatkan kode status 401 dalam
respons.
Jika pengguna yang diberi otorisasi tidak memiliki akses ke akun atau penampung Google Tag Manager, Anda akan mendapatkan kode status 403 dalam respons. Pastikan Anda diberi otorisasi dengan pengguna yang benar dan Anda telah diberi izin untuk mengakses akun atau penampung Tag Manager.
OAuth 2.0 Playground
OAuth 2.0 Playground memungkinkan Anda menjalani seluruh alur otorisasi melalui antarmuka web. Alat ini juga menampilkan semua header permintaan HTTP yang diperlukan untuk membuat kueri yang sah. Jika Anda tidak dapat membuat otorisasi berfungsi di aplikasi Anda sendiri, Anda harus mencoba membuatnya berfungsi melalui OAuth 2.0 Playground. Kemudian, Anda dapat membandingkan header dan permintaan HTTP dari playground dengan yang dikirimkan aplikasi Anda. Pemeriksaan ini adalah cara sederhana untuk memastikan Anda memformat permintaan dengan benar.
Pemberian tidak valid
Jika Anda menerima respons error invalid_grant saat mencoba
menggunakan token refresh, error tersebut mungkin disebabkan oleh salah satu atau kedua
hal berikut:
- Jam server Anda tidak disinkronkan dengan NTP.
- Anda telah melampaui batas token refresh.
Aplikasi dapat meminta beberapa token refresh untuk mengakses satu akun Google Tag Manager. Misalnya, hal ini berguna dalam situasi saat pengguna ingin menginstal aplikasi di beberapa komputer dan mengakses akun Google Tag Manager yang sama. Dalam hal ini, dua token refresh diperlukan, satu untuk setiap penginstalan. Jika jumlah token refresh melampaui batas, token yang lebih lama akan menjadi tidak valid. Jika aplikasi mencoba menggunakan token refresh yang tidak valid, respons errorinvalid_grantakan ditampilkan. Setiap kombinasi ID klien/akun unik dapat memiliki hingga 25 token refresh. (Perhatikan bahwa batas ini dapat berubah sewaktu-waktu.) Jika aplikasi terus meminta token refresh untuk kombinasi Client-ID/akun yang sama, setelah token ke-26 dikeluarkan, token refresh pertama yang dikeluarkan akan menjadi tidak valid. Token refresh ke-27 yang diminta membatalkan token ke-2 yang dikeluarkan, dan seterusnya.