Otorisasi API Tag Manager

Dokumen tersebut menjelaskan cara aplikasi dapat memperoleh otorisasi untuk membuat permintaan ke Tag Manager API.

Mengizinkan Permintaan

Sebelum dapat melihat informasi akun mereka di situs Google mana pun, pengguna harus login dengan Akun Google terlebih dahulu. Dengan cara yang sama, saat pengguna pertama kali mengakses aplikasi Anda, mereka harus mengizinkan aplikasi Anda untuk mengakses data mereka.

Setiap permintaan yang dikirimkan 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 yang diautentikasi.

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:

  1. Saat membuat aplikasi, Anda mendaftarkannya menggunakan Konsol Google API. Selanjutnya, Google menyediakan informasi yang akan Anda perlukan nanti, seperti ID klien dan rahasia klien.
  2. Aktifkan Tag Manager API di Konsol API Google. (Jika API tidak tercantum di Konsol API, lewati langkah ini.)
  3. Saat memerlukan akses ke data pengguna, aplikasi Anda akan meminta cakupan akses tertentu kepada Google.
  4. Google menampilkan layar izin kepada pengguna, yang meminta mereka mengizinkan aplikasi Anda untuk meminta beberapa data.
  5. Jika pengguna menyetujui, Google akan memberikan token akses berumur singkat ke aplikasi Anda.
  6. Aplikasi Anda meminta data pengguna, dengan menambahkan token akses ke permintaan.
  7. 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 adalah 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.
https://www.googleapis.com/auth/tagmanager.manage.accounts Mengelola akun Google Tag Manager.

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, Anda harus terlebih dahulu menggunakan alat penyiapan, yang memandu Anda menyelesaikan pembuatan project di Konsol API Google, mengaktifkan API, dan membuat kredensial.

Untuk menyiapkan akun layanan baru, lakukan hal berikut:

  1. Klik Create credentials > Service account key.
  2. 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 Umum OAuth 2.0

Panduan berikut menguraikan kasus penggunaan umum untuk alur OAuth 2.0 tertentu:

Server Web

Alur ini cocok untuk akses otomatis/offline/terjadwal akun Google Tag Manager pengguna.

Contoh:
  • Memperbarui informasi Tag Manager secara otomatis dari server.

Sisi klien

Cocok digunakan 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.

Contoh:
  • Alat konfigurasi berbasis browser yang disesuaikan.

Aplikasi Terinstal

Untuk aplikasi yang didistribusikan sebagai paket dan diinstal oleh pengguna. Pengujian ini mengharuskan aplikasi atau pengguna memiliki akses ke browser untuk menyelesaikan alur autentikasi.

Contoh:
  • Widget desktop di PC atau Mac.
  • Plugin untuk sistem pengelolaan konten. Manfaat alur ini dibandingkan dengan server web atau sisi klien adalah bahwa 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 akun Google Tag Manager Anda sendiri. Misalnya, untuk membuat alat kustom guna memantau akun Google Tag Manager Anda sendiri dan membagikannya dengan pengguna lain.

Pemecahan masalah

Jika masa berlaku access_token telah berakhir 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 penampung atau akun Google Tag Manager, Anda akan mendapatkan kode status 403 dalam respons. Pastikan Anda diberi otorisasi dengan pengguna yang benar dan telah diberi izin untuk mengakses akun atau penampung Tag Manager.

OAuth 2.0 Playground

OAuth 2.0 Playground memungkinkan Anda melewati seluruh alur otorisasi melalui antarmuka web. Alat ini juga menampilkan semua header permintaan HTTP yang diperlukan untuk membuat kueri yang diotorisasi. Jika Anda tidak mendapatkan otorisasi untuk berfungsi di aplikasi Anda sendiri, Anda harus mencoba agar otorisasi berfungsi melalui OAuth 2.0 Playground. Kemudian, Anda dapat membandingkan header HTTP dan permintaan dari playground dengan apa yang dikirim 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:

  1. Jam server Anda tidak sinkron dengan NTP.
  2. 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, diperlukan dua token refresh, satu untuk setiap penginstalan. Jika jumlah token refresh melebihi batas, token yang lebih lama akan menjadi tidak valid. Jika aplikasi mencoba menggunakan token refresh yang tidak valid, respons error invalid_grant akan ditampilkan. Setiap kombinasi client-ID/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 yang diminta ke-27 membatalkan token ke-2 yang diterbitkan, dan seterusnya.