Referensi Measurement Protocol

Dokumen ini menjelaskan cara mengirim data ke Google Analytics menggunakan Measurement Protocol.

Ringkasan

Ada 2 bagian untuk mengirim data ke Google Analytics menggunakan Measurement Protocol:

  • Transportasi – ke mana dan bagaimana Anda mengirimkan data
  • Payload – data yang Anda kirim

Dokumen ini menjelaskan cara memformat keduanya.

Transpor

Endpoint URL

Anda mengirim data menggunakan Measurement Protocol dengan membuat permintaan HTTP ke endpoint berikut:

https://www.google-analytics.com/collect

Semua data harus dikirim dengan aman menggunakan protokol HTTPS.

Anda dapat mengirim data menggunakan permintaan POST atau GET.

Menggunakan POST

Sebaiknya kirim data melalui POST karena cara ini memungkinkan payload yang lebih besar. Saat menggunakan POST, berikan permintaan HTTP berikut:

User-Agent: user_agent_string
POST https://www.google-analytics.com/collect
payload_data

Dengan keterangan:

  • user_agent_string – Adalah string agen pengguna berformat yang digunakan untuk menghitung dimensi berikut: kemampuan browser, platform, dan seluler.

    Jika nilai ini tidak ditetapkan, data di atas tidak akan dihitung.

  • payload_dataBODY dari permintaan postingan. Isi harus menyertakan 1 payload berenkode URI dan tidak boleh lebih dari 8.192 byte.
  • Alamat IP – Dikirim secara implisit dalam permintaan HTTP dan digunakan untuk menghitung semua dimensi geografis / jaringan di Google Analytics.

GET

Untuk lingkungan yang tidak memungkinkan pengiriman data POST, Anda juga dapat mengirim permintaan HTTP GET ke endpoint yang sama:

GET /collect?payload_data HTTP/1.1
Host: https://www.google-analytics.com
User-Agent: user_agent_string

Tempat data payload dikirim sebagai parameter kueri yang di-escape URI. Panjang seluruh URL yang dienkodekan tidak boleh lebih dari 8.000 Byte.

Perusak Cache

Di beberapa lingkungan, seperti browser, permintaan GET HTTP mungkin di-cache. Jika permintaan di-cache, permintaan berikutnya mungkin diambil dari cache, dan tidak dikirim ke Google Analytics. Untuk menembus cache, Measurement Protocol menyediakan parameter khusus (z) yang dapat ditetapkan dengan angka acak. Hal ini memastikan semua permintaan Measurement Protocol bersifat unik, dan permintaan berikutnya tidak diambil dari cache.

Saat Anda menggunakan perusak cache, sebaiknya tambahkan parameter ini sebagai parameter terakhir dalam payload.

https://www.google-analytics.com/collect?payload_data&z=123456

Kode Respons

Measurement Protocol akan menampilkan kode status 2xx jika permintaan HTTP diterima. Measurement Protocol tidak menampilkan kode error jika format data payload salah, atau jika data dalam payload salah atau tidak diproses oleh Google Analytics.

Jika Anda tidak mendapatkan kode status 2xx, Anda sebaiknya TIDAK mencoba lagi permintaan tersebut. Sebagai gantinya, Anda harus berhenti dan memperbaiki error dalam permintaan HTTP.

Data Payload

Semua data yang dikumpulkan oleh Google Analytics menggunakan Measurement Protocol dikirim sebagai payload. Payload ini menyerupai string kueri URL, di mana setiap parameter memiliki kunci dan nilai, dipisahkan dengan karakter =, dan setiap pasangan dipisahkan oleh karakter &. Contoh:

key1=val1&key2=val2

Setiap payload memiliki aturan yang mengatur: nilai yang diperlukan, encoding URI, parameter yang dapat dikirim bersama, dan panjang parameter. Selain itu, setiap parameter memiliki jenis tertentu yang memerlukan format tertentu. Bagian berikut membahas aturan ini.

Baca Referensi Parameter untuk melihat daftar lengkap semua parameter yang dapat Anda kirim menggunakan Measurement Protocol.

Nilai yang Diperlukan untuk Semua Klik

Parameter berikut harus ada dalam setiap payload:

Nama Parameter Contoh Deskripsi
Versi Protokol v v=1 Versi protokol. Nilai harus berupa 1.
ID Pelacakan tid tid=UA-123456-1 ID yang membedakan properti Google Analytics mana yang akan mengirim data.
Client ID cid cid=xxxxx ID unik untuk pengguna tertentu.
Jenis Hit t t=pageview Jenis interaksi yang dikumpulkan untuk pengguna tertentu.

Data Client ID dan Hit Type adalah nilai yang dipetakan langsung ke model data Google Analytics. Jika ingin melacak pengguna 5555 yang menuju ke /pageA, /pageB, dan /pageC, Anda harus mengirimkan 3 payload berikut:

v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageA
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageB
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageC

Perhatikan bahwa / dienkode ke %2F.

Nilai Encoding URL

Semua nilai yang dikirim ke Google Analytics harus berupa UTF-8 dan Dienkode URL. Untuk mengirim kunci dp dengan nilai /my page €, Anda harus memastikan terlebih dahulu bahwa kunci ini dienkode dengan UTF-8, lalu dienkode ke URL, sehingga menghasilkan string akhir:

dp=%2Fmy%20page%20%E2%82%AC

Jika salah satu karakter dienkode dengan tidak benar, karakter tersebut akan diganti dengan karakter pengganti unicode xFFFD.

Nilai yang Diperlukan untuk Jenis Hit Tertentu

Beberapa parameter hanya dapat dikirim dengan jenis hit tertentu. Misalnya, jenis hit pageview mengharuskan parameter Jalur Halaman (dp) juga ditetapkan. Referensi Parameter menjelaskan parameter yang diperlukan untuk setiap jenis hit.

Panjang Maksimum

Beberapa nilai teks dalam Measurement Protocol memiliki panjang maksimum spesifik dalam byte. Misalnya, kolom perujuk dokumen dr memiliki panjang maksimum 2.048 Byte. Jika ada salah satu nilai yang lebih besar dari panjang maksimum, nilai tersebut akan otomatis dipotong. Jika karakter multi-byte melebihi panjang maksimum, seluruh karakter akan terpotong.

Jenis Data yang Didukung

Setiap kolom data di Measurement Protocol termasuk dalam jenis tertentu, masing-masing dengan aturan validasinya sendiri. Jika salah satu parameter value tidak sesuai dengan aturan validasi, parameter tertentu tersebut akan diabaikan dan tidak diproses oleh Google Analytics. Semua parameter lainnya akan diproses seperti biasa.

Measurement Protocol mendukung jenis data berikut:

Perhatikan bahwa setiap kolom data mungkin memiliki batasannya sendiri. Baca Referensi Kolom untuk melihat daftar lengkap semua kolom data dan jenis yang diterima.

Teks

Digunakan untuk merepresentasikan string. Pemrosesan tambahan dilakukan pada kolom teks. Semua karakter spasi kosong di awal dan di akhir akan dihapus. Operasi internal dari dua karakter spasi kosong atau lebih (termasuk spasi, tab, baris baru, dll.) dikurangi menjadi satu karakter spasi. Transformasi ini diterapkan pada teks mentah sebelum pemotongan dilakukan. Contoh:

   Hello      World

akan menjadi:

Hello World

Mata uang

Digunakan untuk merepresentasikan total nilai mata uang. Titik desimal digunakan sebagai pembatas antara bagian keseluruhan dan pecahan dari mata uang. Presisinya adalah maksimal 6 angka di belakang koma. Hal berikut valid untuk kolom mata uang:

1000.000001

Setelah nilai dikirim ke Google Analytics, semua teks dihapus hingga digit pertama, karakter - atau karakter . (desimal). Jadi:

$-55.00

akan menjadi:

-55.00

Boolean

Digunakan untuk menentukan apakah suatu nilai benar atau salah. Nilai yang valid adalah:

  • 1 – Benar
  • 0 – Salah

Bilangan Bulat

Digunakan untuk mewakili bilangan bulat. Nilai disimpan sebagai int64 yang ditandatangani

Angka

Digunakan untuk menyatakan bilangan bulat atau bilangan floating point.