Menyediakan Akun yang Dikontrol Pengguna – Panduan Developer API

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:

  1. Daftarkan aplikasi Anda di Konsol API Google.
  2. Otorisasi untuk membuat akun Google Analytics baru.
  3. 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:

  1. Minta pengguna untuk mengautentikasi dan memberi otorisasi aplikasi/layanan menggunakan OAuth 2.0.
  2. Membuat Tiket Akun menggunakan Provisioning API.
  3. Alihkan pengguna untuk menyetujui Persyaratan Layanan (TOS) Google Analytics dan menangani responsnya.
  4. (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

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 atau edit.
  • 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.
  • Kolom Properti Web
    • Properti name wajib ada untuk properti tersebut.
    • websiteUrl wajib diisi.
  • Kolom profil
    • Properti name wajib ada untuk profil.
    • timezone dapat diberikan secara opsional. Default-nya adalah America/Los_Angeles.

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:

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:

  1. Buat Akun Google Analytics
  2. 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:

  1. 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.
  2. Pengguna akan diminta untuk mengizinkan aplikasi ‘Membuat Akun Google Analytics’.
  3. Pengguna menyetujui permintaan izin untuk aplikasi.
  4. Pengguna dialihkan ke Penyedia Layanan. Perlu diperhatikan bahwa jika pengguna menolak otorisasi, mereka akan tetap dialihkan kembali ke Penyedia Layanan.
  5. Formulir ditampilkan kepada pengguna untuk mengumpulkan detail tentang akun yang akan dibuat (misalnya Nama akun, nama properti, nama profil, zona waktu, URL situs, dll.)
  6. Pengguna mengisi dan mengirimkan formulir, lalu dialihkan ke Google/ditampilkan Persyaratan Layanan (TOS) Google Analytics.
  7. Pengguna menyetujui TOS.
  8. 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:

  1. 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).
  2. 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.
  3. Pengguna akan diminta untuk mengizinkan aplikasi ‘Membuat Akun Google Analytics’.
  4. Pengguna menerima izin yang diminta untuk aplikasi.
  5. Pengguna dialihkan ke Penyedia Layanan.
  6. Pengguna dialihkan ke Google/ditampilkan Persyaratan Layanan (TOS) Google Analytics.
  7. Pengguna menyetujui TOS.
  8. 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.