Dokumen ini menjelaskan konsep penting tentang penggunaan Provisioning API untuk membuat akun Google Analytics baru.
Pengantar
API Penyediaan dapat digunakan untuk membuat akun Google Analytics baru dan mengaktifkan Google Analytics untuk pelanggan Anda dalam skala besar. Halaman ini ditujukan bagi penyedia layanan yang memenuhi syarat dan partner besar. Kunjungi Ringkasan Provisioning API untuk pengantar Provisioning API.
Sebelum Memulai
Semua Google Analytics API diakses dengan cara yang sama. Sebelum memulai dengan Provisioning API, Anda harus:
- Baca halaman client libraries untuk melihat daftar lengkap library klien khusus bahasa pemrograman yang bekerja dengan API.
- Baca Panduan Referensi untuk mempelajari antarmuka API dan cara mengakses data tanpa library klien.
Setiap library klien menyediakan satu objek layanan analisis untuk mengakses Provisioning API. Untuk membuat objek layanan, Anda biasanya harus melakukan langkah-langkah berikut:
- Daftarkan aplikasi Anda di Konsol API Google.
- Otorisasi untuk membuat akun Google Analytics baru.
- Buat objek layanan Analytics.
Jika Anda belum menyelesaikan langkah-langkah ini, berhentilah dan baca Tutorial API Google Analytics yang terhormat. Tutorial ini akan memandu Anda melalui langkah-langkah awal pembuatan aplikasi Google Analytics API. Setelah selesai, Anda akan memahami cara mengakses Google Analytics API untuk melakukan tugas di dunia nyata.
Ringkasan
Saat membuat akun Google Analytics menggunakan Provisioning API, ada 2 alur terpisah yang perlu dipertimbangkan:
- Alur Teknis: Alur end-to-end untuk menyediakan akun Google Analytics secara terprogram bagi pengguna.
- Alur Pengguna: Pertimbangan penerapan yang harus Anda buat untuk alur pembuatan akun dari perspektif pengguna.
Dokumen ini menjelaskan langkah-langkah dan persyaratan tingkat tinggi untuk setiap alur.
Alur Teknis
Langkah-langkah tingkat tinggi dalam menggunakan Provisioning API untuk membuat akun baru dan berintegrasi dengan Google Analytics adalah:
- Minta pengguna untuk mengautentikasi dan memberi otorisasi aplikasi/layanan menggunakan OAuth 2.0.
- Membuat Tiket Akun menggunakan Provisioning API.
- Alihkan pengguna untuk menyetujui Persyaratan Layanan (TOS) Google Analytics dan menangani responsnya.
- (Opsional) Konfigurasi akun dan peluang integrasi.
Jika semua langkah ini berhasil diselesaikan, akun Google Analytics akan dibuat untuk pengguna dan Anda akan memiliki ID Akun, ID Properti, dan ID Tampilan (Profil) untuk akun baru tersebut.
Untuk setiap langkah di bawah ini, terdapat Persyaratan untuk menyelesaikan langkah, Hasil langkah, dan deskripsi Alur Teknis untuk langkah tersebut.
1. Autentikasi dan Otorisasi
Setiap pengguna harus memberikan otorisasi kepada aplikasi Anda dan memberikannya kemampuan untuk menyediakan akun Google Analytics atas nama mereka. Alur aplikasi OAuth 2.0 Web Server disarankan untuk melakukan langkah ini.
Yang Anda perlukan untuk menyelesaikan langkah ini
- Client ID -
Client ID
project yang akan Anda gunakan. Opsi ini tersedia di Google Developers Console. Baca alur Server Web OAuth 2.0 untuk mempelajari lebih lanjut. - URI Pengalihan - Ini adalah tempat pengguna dialihkan dan respons OAuth 2.0 dikirim.
- Konfigurasikan
Redirect URIs
dan dapatkanClient ID
untuk project Anda menggunakan Google Developers Console. - Nilai parameter ini harus sama persis dengan salah satu nilai yang terdaftar di Google Developers Console (termasuk skema http atau https, kasus, dan tanda '/').
- Konfigurasikan
- Cakupan Auth untuk API Penyediaan Google Analytics
Hasil dari langkah ini
Setelah alur OAuth 2.0 selesai, pengguna akan memberi aplikasi otorisasi untuk menyediakan akun atas nama mereka, dan Anda akan memiliki Token Akses untuk pengguna.
Catatan tentang Token dan Cakupan:
- Jika ingin membuat permintaan tambahan untuk konfigurasi akun atau data pelaporan pengguna setelah akun dibuat, Anda juga dapat mengizinkan cakupan tambahan selama langkah ini. Misalnya, cakupan
readonly
atauedit
. - Token akses memiliki masa berlaku yang terbatas. Jika aplikasi Anda memerlukan akses ke Google Analytics API setelah masa berlaku token akses tunggal habis, Anda juga dapat meminta token refresh dengan menetapkan
access_type=offline
. Token Refresh harus disimpan dalam penyimpanan jangka panjang yang aman untuk setiap pengguna karena memungkinkan aplikasi Anda memperoleh token akses baru. Lihat Akses offline untuk mengetahui detail tambahan.
Alur teknis untuk langkah ini
Anda perlu mendapatkan Token Akses untuk pengguna. Berdasarkan alur yang dijelaskan di Server Web OAuth 2.0, kirim pengguna ke layanan Akun Google, lalu tangani respons saat pengguna dialihkan kembali ke layanan Anda setelah menyelesaikan alur autentikasi.
Buat URL OAuth 2.0 yang akan dikunjungi pengguna
Saat pengguna mengklik tombol atau link untuk Memulai atau Membuat Akun, link harus mengarah ke awal alur OAuth 2.0 untuk meminta pengguna memberikan izin penyediaan. Contoh:
https://accounts.google.com/o/oauth2/auth? scope=https://www.googleapis.com/auth/analytics.provision &redirect_uri={YOUR REDIRECT URI for OAUTH} &response_type=code &client_id={YOUR CLIENT ID}
Menangani Respons dari Layanan Akun Google
Setelah pengguna membuat keputusan untuk memberikan akses ke aplikasi Anda, mereka akan dialihkan ke redirect_uri
seperti yang ditentukan dalam URL yang Anda buat dengan parameter kueri yang berisi kode otorisasi. Jika pengguna menyetujui
permintaan tersebut, respons kode otorisasi dapat digunakan untuk menukar
kode otorisasi dengan token akses dengan membuat permintaan POST
ke
Google Accounts API.
Simpan Token Penyegaran (jika ada)
Token akses ini akan digunakan pada langkah berikutnya, sehingga Anda dapat menyimpannya untuk sementara. Jika Anda juga meminta token refresh untuk pengguna, sebaiknya simpan token ini dengan aman untuk penggunaan jangka panjang. Token refresh berumur panjang dan dapat digunakan untuk menerbitkan token akses baru.
2. Membuat Tiket Akun menggunakan Provisioning API
Setelah memiliki token akses untuk pengguna yang diberi otorisasi, Anda dapat menggunakannya untuk membuat permintaan ke Provisioning API guna membuat Tiket Akun bagi pengguna. Tiket Akun adalah langkah pertama untuk membuat akun bagi pengguna.
Yang Anda perlukan untuk menyelesaikan langkah ini
Token akses untuk pengguna yang diberi otorisasi seperti yang dijelaskan dalam Autentikasi dan Otorisasi dan detail penyediaan berikut:
- URI Pengalihan
- Menentukan tempat pengguna dialihkan setelah halaman Persyaratan Layanan (TOS) Google Analytics. URL ini bisa berbeda dengan URI pengalihan yang ditentukan selama alur otorisasi OAuth 2.0.
- Nilai parameter URI Pengalihan harus sama persis dengan salah satu nilai yang terdaftar di Google Developers Console (termasuk skema http atau https, kasus, dan '/' di akhir).
- Kolom akun
- Properti
name
wajib ada untuk akun.
- Properti
- Kolom Properti Web
- Properti
name
wajib ada untuk properti tersebut. websiteUrl
wajib diisi.
- Properti
- Kolom profil
- Properti
name
wajib ada untuk profil. timezone
dapat diberikan secara opsional. Default-nya adalahAmerica/Los_Angeles
.
- Properti
Saat membuat tiket akun, hanya kolom dasar yang diidentifikasi di atas yang dapat ditetapkan. Setelah akun dibuat, semua perubahan konfigurasi tambahan pada properti atau tampilan (profil) dapat dilakukan menggunakan Management API.
Lihat Referensi API untuk Akun, Properti, dan Tampilan (Profil) untuk mengetahui detail tambahan tentang kolom ini.
Hasil dari langkah ini
Setelah permintaan yang berhasil dibuat ke Provisioning API, Anda akan memiliki Tiket Akun yang berlaku dalam waktu singkat untuk pengguna. ID Tiket Akun digunakan pada langkah terakhir untuk meminta pengguna menyetujui Persyaratan Layanan (TOS) dan mengaktifkan akunnya. Akun tidak dapat digunakan sebelum TOS disetujui.
Alur teknis untuk langkah ini
Dengan menggunakan token akses untuk pengguna yang diperoleh selama Autentikasi dan Otorisasi, permintaan HTTP
POST
dibuat ke Provisioning API.
Permintaan API Penyediaan untuk membuat Tiket Akun
Tinjau metode
createAccountTicket
dalam referensi API Penyediaan untuk mengetahui detail tentang cara membuat permintaan.
Respons dari Provisioning API
Permintaan yang berhasil akan menampilkan respons 200. Isi respons berisi Tiket Akun, yang berumur pendek. Tiket akun terdiri dari ID dan detail untuk hierarki akun baru.
Tinjau
Account Ticket resource
dalam referensi Provisioning API
untuk mengetahui detail tentang respons.
Respons error juga perlu ditangani oleh aplikasi.
3. Pengguna Menyetujui Persyaratan Layanan Google Analytics (TOS)
Setelah memiliki ID Tiket Akun untuk pengguna, Anda dapat menggunakannya dengan permintaan TOS untuk meminta pengguna menyetujui Persyaratan Layanan Google Analytics.
Yang Anda perlukan untuk menyelesaikan langkah ini
ID Tiket Akun untuk pengguna yang diotorisasi.
Hasil dari langkah ini
Setelah berhasil menyelesaikan Alur TOS menggunakan ID Tiket Akun, akun, properti, dan tampilan (profil) akan dibuat. Pengguna kini akan memiliki akun yang aktif. Respons dari halaman TOS akan menyertakan ID Akun, ID Properti, dan ID Tampilan (Profil).
Alur teknis untuk langkah ini
Dengan menggunakan ID Tiket Akun, alihkan pengguna ke halaman TOS Google Analytics tempat mereka dapat menyetujui TOS, lalu Anda harus menangani respons dari API.
Buat URL TOS untuk dikunjungi pengguna
Alihkan pengguna ke halaman TOS dan sertakan ID Tiket Akun sebagai bagian dari URL:
https://analytics.google.com/analytics/web/?provisioningSignup=false#/termsofservice/{account_ticket_id}
Menangani respons TOS
Setelah pengguna melakukan beberapa tindakan di halaman TOS, mereka akan dialihkan kembali ke redirectUri
yang ditentukan saat pembuatan tiket akun. Respons dari halaman TOS
akan disertakan sebagai bagian dari string kueri.
Respons yang berhasil akan menampilkan data tentang struktur akun yang baru
dibuat serta accountTicketId
asli:
https://{YOUR REDIRECT URI for TOS}? accountId={accountId} &webPropertyId={webPropertyId} &profileId={profileId} &accountTicketId={accountTicketId}
Misalnya, jika pengendali TOS untuk aplikasi Anda berada di http://www.your-app.com/gaTOS
, pengendali TOS harus ditetapkan sebagai redirectUri
saat membuat tiket akun. Pengendali TOS aplikasi Anda harus mengharapkan dan menangani dengan benar permintaan HTTP GET
yang berisi parameter kueri accountId
, webPropertyId
, profileId
, dan accountTicketId
untuk kasus saat tiket akun valid dan pengguna telah menyetujui TOS.
Respons yang gagal akan menyertakan respons error:
https://{YOUR REDIRECT URI for TOS}? error={error_code} &accountTicketId={accountTicketId}
Pengendali TOS Anda juga harus menangani permintaan HTTP GET
yang berisi parameter kueri error
dengan benar, yang menunjukkan adanya
error. Nilai parameter kueri dapat digunakan untuk mengambil tindakan lebih lanjut atau
menampilkan pesan kepada pengguna:
error=user_cancel
- Pengguna tidak menyetujui persyaratan layanan.error=max_accounts_reached
- Pengguna telah mencapai batas akun Google Analytics.error=backend_error
- Error umum. Server menampilkan error yang tidak ada dalam kategori di atas.
4. (Opsional) Peluang Integrasi
Jika Anda telah mengikuti Alur Teknis di atas, Anda akan membuat akun untuk pengguna dan akan memiliki ID Akun, ID Properti, dan ID Tampilan (Profil). Jika Anda juga meminta izin tambahan, Anda mungkin juga memiliki token refresh untuk pengguna. Dengan data ini, Anda dapat:
- Jika relevan, masukkan cuplikan pelacakan Google Analytics standar secara otomatis dengan ID Properti dari akun yang baru dibuat untuk setiap halaman di situs pengguna.
- Secara otomatis mengonfigurasi Properti pengguna menggunakan Management API.
- Berikan laporan untuk pengguna dalam produk Anda (misalnya di panel admin) menggunakan Embed API atau Core Reporting API.
Alur Pengguna
Bagian ini menjelaskan pertimbangan penerapan yang terkait dengan langkah-langkah alur pembuatan akun dari perspektif pengguna.
Alurnya dimulai dengan pengguna menawarkan 2 opsi berikut untuk mengaktifkan analisis untuk properti mereka:
- Buat Akun Google Analytics
- Gunakan akun Google Analytics yang ada. (Catatan: Alur ini tidak dibahas dalam dokumen ini. Lihat Management API untuk mengetahui detail tentang cara mengakses data konfigurasi Google Analytics pengguna.)
Saat membuat akun Google Analytics baru, ada informasi yang wajib Anda kirimkan bersama dengan permintaan penyediaan seperti nama akun, nama properti, dsb. Bergantung pada informasi yang Anda miliki tentang pengguna dan alur pilihan yang ingin Anda tunjukkan kepada mereka, ada 3 opsi utama untuk memulai alur penggunaan setelah pengguna mengklik 'buat akun':
Minta detail rekening setelah otorisasi
Dalam hal ini, pengguna akan dimintai detail akun di tengah proses. Alurnya akan terlihat seperti berikut:
- Pengguna akan dialihkan ke Google Account Service untuk alur OAuth 2.0. Jika tidak memiliki Akun Google atau tidak login, pengguna akan diminta untuk membuat Akun Google atau login.
- Pengguna akan diminta untuk mengizinkan aplikasi ‘Membuat Akun Google Analytics’.
- Pengguna menyetujui permintaan izin untuk aplikasi.
- Pengguna dialihkan ke Penyedia Layanan. Perlu diperhatikan bahwa jika pengguna menolak otorisasi, mereka akan tetap dialihkan kembali ke Penyedia Layanan.
- Formulir ditampilkan kepada pengguna untuk mengumpulkan detail tentang akun yang akan dibuat (misalnya Nama akun, nama properti, nama profil, zona waktu, URL situs, dll.)
- Pengguna mengisi dan mengirimkan formulir, lalu dialihkan ke Google/ditampilkan Persyaratan Layanan (TOS) Google Analytics.
- Pengguna menyetujui TOS.
- Pengguna dialihkan ke Penyedia Layanan dan akan melihat beberapa pesan berhasil yang menyatakan bahwa mereka telah berhasil membuat akun Google Analytics dengan detail tentang akun tersebut dan cara mengaksesnya. Perhatikan bahwa jika pengguna tidak menyetujui TOS, mereka akan tetap dialihkan kembali ke Penyedia Layanan.
Minta detail rekening sebelum otorisasi
Dalam hal ini, pengguna diminta di awal untuk memberikan detail konfigurasi akun yang akan dibuat. Alurnya akan terlihat seperti berikut:
- Di situs Penyedia Layanan, formulir ditampilkan kepada pengguna untuk mengumpulkan detail tentang akun yang akan dibuat (misalnya Nama akun, nama properti, nama profil, zona waktu, URL situs).
- Pengguna mengisi formulir, mengklik kirim, dan dialihkan ke alur Google Account Service untuk OAuth 2.0. Jika tidak memiliki Akun Google atau tidak login, pengguna akan diminta membuat Akun Google atau login.
- Pengguna akan diminta untuk mengizinkan aplikasi ‘Membuat Akun Google Analytics’.
- Pengguna menerima izin yang diminta untuk aplikasi.
- Pengguna dialihkan ke Penyedia Layanan.
- Pengguna dialihkan ke Google/ditampilkan Persyaratan Layanan (TOS) Google Analytics.
- Pengguna menyetujui TOS.
- Pengguna dialihkan ke Penyedia Layanan dan akan melihat beberapa pesan berhasil yang menyatakan bahwa mereka telah berhasil membuat akun Google Analytics dengan detail tentang akun tersebut dan cara mengaksesnya.
Isi otomatis detail akun atau lewati formulir
Jika informasi tentang akun pengguna sudah tersedia (misalnya, URL situs, nama situs, zona waktu, dll.), kedua opsi di atas dapat lebih disederhanakan dengan:
- Melakukan pra-pengisian formulir dan memungkinkan pengguna untuk mengedit jika mereka ingin
- Melewati langkah formulir sepenuhnya dan membuat akun secara otomatis menggunakan informasi yang ada.