Referensi Measurement Protocol

Halaman ini menjelaskan mekanisme transpor dan parameter data untuk Measurement Protocol.

Transpor

Semua data harus dikirim dengan aman menggunakan permintaan HTTPS POST.

Kirim permintaan ke endpoint berikut:

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

Jika Anda ingin data Anda dikumpulkan di Uni Eropa, gunakan endpoint berikut:

https://region1.google-analytics.com/mp/collect

Berikut adalah contoh permintaan POST:

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
PAYLOAD_DATA

Ganti PAYLOAD_DATA dengan Payload permintaan.

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

Payload

Payload memiliki dua bagian:

  1. Parameter kueri.
  2. Isi POST JSON.

Parameter kueri

Nama Parameter Deskripsi

api_secret

 Wajib diisi. Rahasia API dari UI Google Analytics.

Dapat ditemukan di Admin > Aliran Data > Pilih aliran data Anda > Measurement Protocol > Buat.

Pribadi untuk organisasi Anda. Harus diperbarui secara rutin untuk menghindari SPAM yang berlebihan.

firebase_app_id

 Wajib diisi. ID Aplikasi Firebase. ID untuk aplikasi Firebase.

Dapat ditemukan di Firebase console di bagian Setelan Project > General > Your Apps > App ID.

Isi JSON POST

Ukuran isi POST JSON harus kurang dari 130 kB.

Kunci Jenis Deskripsi

app_instance_id

 string Wajib diisi. ID unik untuk penginstalan tertentu dari aplikasi Firebase.

Tidak sama dengan client_id web.

Harus diambil menggunakan Firebase SDK:

user_id

 string

Opsional. ID unik untuk pengguna. Lihat artikel User-ID untuk analisis lintas platform guna mendapatkan informasi lebih lanjut tentang ID ini. Hanya boleh berisi karakter UTF-8.

timestamp_micros

 number

Opsional. Stempel waktu Unix, mikrodetik, bukan milidetik. Menunjukkan waktu peristiwa. Hanya boleh disetel untuk mencatat peristiwa yang terjadi di masa lalu. Dapat diganti oleh user_property atau stempel waktu peristiwa. Tanggal peristiwa dapat ditetapkan ke maksimal 72 jam sebelumnya.

user_properties

 object Opsional. Properti pengguna untuk pengukuran. Maksimal 25 properti pengguna dapat dikirim per permintaan. Nama properti pengguna harus terdiri dari maksimal 24 karakter, dan nilai properti pengguna harus terdiri dari maksimal 36 karakter.

user_data

 object Opsional. Data yang disediakan pengguna.
object Opsional. Setelan izin untuk permintaan. Lihat bagian izin untuk mengetahui informasi selengkapnya.

non_personalized_ads

 boolean Opsional. Tetapkan ke true untuk mengindikasikan bahwa data pengguna tidak boleh digunakan untuk iklan yang dipersonalisasi.

user_location

 object Opsional. Menetapkan informasi geografis untuk permintaan dalam format terstruktur.

ip_override

 string Opsional. Alamat IP yang digunakan Google Analytics untuk mendapatkan informasi geografis untuk permintaan.

device

 object Opsional. Menetapkan informasi perangkat untuk permintaan dalam format terstruktur.

validation_behavior

 string

Opsional. Menetapkan perilaku validasi untuk permintaan.

RELAXED atau ENFORCE_RECOMMENDATIONS. Jika tidak ditentukan, setelan defaultnya adalah RELAXED.

events[]

 array Wajib diisi. Array item event. Maksimal 25 peristiwa dapat dikirim per permintaan. Lihat referensi peristiwa untuk mengetahui peristiwa yang direkomendasikan.

events[].name

 string Wajib diisi. Nama peristiwa. Nama peristiwa tidak boleh lebih dari 40 karakter. Lihat Peristiwa untuk mengetahui peristiwa yang direkomendasikan.

events[].params

 object Opsional. Parameter untuk peristiwa. Maksimal 25 parameter dapat dikirim per peristiwa. Lihat Peristiwa untuk mengetahui parameter yang direkomendasikan untuk setiap peristiwa, dan Parameter peristiwa umum.

Nama parameter harus terdiri dari 40 karakter atau kurang. Nilai parameter harus terdiri dari 100 karakter atau kurang untuk properti Google Analytics standar, dan 500 karakter atau kurang untuk properti Google Analytics 360.

Parameter peristiwa umum

Measurement Protocol memiliki parameter peristiwa umum berikut:

Kunci Jenis Deskripsi

session_id

 number Angka positif yang mengidentifikasi sesi pengguna. Diperlukan untuk beberapa kasus penggunaan umum. Harus cocok dengan ekspresi reguler ^\d+$.

Harus diambil menggunakan Firebase SDK:

engagement_time_msec

 number Durasi engagement pengguna, dalam milidetik, untuk peristiwa. Gunakan nilai yang mencerminkan jumlah waktu engagement pengguna sejak peristiwa sebelumnya.

timestamp_micros

 number Waktu epoch Unix, dalam mikrodetik, untuk peristiwa. Gunakan parameter ini untuk mengganti stempel waktu peristiwa.

Atribut consent mengonfigurasi jenis dan status izin. Jika Anda tidak menentukan consent, Google Analytics akan menggunakan setelan izin dari interaksi online yang sesuai untuk instance klien atau aplikasi.

Kunci Jenis Deskripsi

ad_user_data

 string

Opsional. Izin untuk mengirim data pengguna dari peristiwa dan properti pengguna permintaan ke Google untuk tujuan iklan.

GRANTED atau DENIED.

ad_personalization

 string

Opsional. Izin untuk iklan yang dipersonalisasi bagi pengguna.

GRANTED atau DENIED.

Informasi geografis

Atribut user_location dan ip_override memberikan informasi geografis. user_location lebih diprioritaskan daripada ip_override.

Berikut adalah struktur kolom user_location. Berikan atribut sebanyak mungkin. Sebaiknya gunakan minimal country_id dan region_id.

Kunci Jenis Deskripsi

city

 string Opsional. Nama kota. Jika kota berada di Amerika Serikat, tetapkan juga country_id dan region_id agar Google Analytics dapat memetakan nama kota dengan benar ke ID kota.

region_id

 string Opsional. Negara dan subdivisi ISO 3166. Misalnya, US-CA, US-AR, CA-BC, GB-LND, CN-HK.

country_id

 string Opsional. Negara dalam format ISO 3166-1 alpha-2. Misalnya, US, AU, ES, FR.

subcontinent_id

 string Opsional. Subbenua dalam format UN M49. Misalnya, 011, 021, 030, 039.

continent_id

 string Opsional. Benua dalam format UN M49. Misalnya, 002, 019, 142, 150.

Berikut adalah contoh user_location:

"user_location": {
  "city": "Mountain View",
  "region_id": "US-CA",
  "country_id": "US",
  "subcontinent_id": "021",
  "continent_id": "019"
}

ip_override adalah alternatif untuk user_location. Jika Anda mengirim ip_override, Google Analytics akan memperoleh informasi geografis dari alamat IP. Jika Anda mengirim user_location, Google Analytics akan mengabaikan ip_override.

Jika Anda tidak mengirim user_location atau ip_override, Google Analytics akan memperoleh informasi geografis dari peristiwa pemberian tag menggunakanapp_instance_id.

Google Analytics menerapkan setelan data lokasi terperinci properti ke permintaan, terlepas dari informasi geografis yang dikirim.

Informasi perangkat

Untuk mengirim informasi perangkat, gunakan kolom device. Berikut adalah struktur kolom device. Berikan atribut sebanyak mungkin. Sebaiknya gunakan minimal category.

Kunci Jenis Deskripsi

category

 string Opsional. Kategori perangkat. Misalnya, desktop, tablet, mobile, smart TV.

language

 string Opsional. Bahasa dalam format ISO 639-1. Contoh, en, en-US.

screen_resolution

 string Opsional. Resolusi perangkat, yang diformat sebagai WIDTHxHEIGHT. Misalnya, 1280x2856, 1080x2340.

operating_system

 string Opsional. Sistem operasi atau platform. Contoh, MacOS.

operating_system_version

 string Opsional. Versi sistem operasi atau platform. Contohnya 13.5.

model

 string Opsional. Model perangkat. Misalnya, Pixel 9 Pro, Samsung Galaxy S24.

brand

 string Opsional. Merek perangkat. Misalnya, Google, Samsung.

browser

 string Opsional. Merek atau jenis browser. Misalnya, Chrome, Firefox.

browser_version

 string Opsional. Versi browser. Misalnya, 136.0.7103.60, 5.0.

Cuplikan berikut menunjukkan contoh setelan device:

"device": {
  "category": "mobile",
  "language": "en",
  "screen_resolution": "1280x2856",
  "operating_system": "Android",
  "operating_system_version": "14",
  "model": "Pixel 9 Pro",
  "brand": "Google",
  "browser": "Chrome",
  "browser_version": "136.0.7103.60"
}
Jika permintaan tidak menentukan device, Google Analytics akan memperoleh informasi perangkat dari peristiwa pemberian tag menggunakan app_instance_id.

Terlepas dari apakah Anda menentukan device, Google Analytics menerapkan setelan data perangkat terperinci properti ke permintaan.

Perilaku validasi

Atribut validation_behavior mengontrol cara Measurement Protocol memvalidasi konten permintaan.

  • Validasi RELAXED hanya menolak permintaan yang salah format. Alat ini mungkin masih menerima peristiwa dan parameter dengan nama kolom yang tidak valid atau dengan data yang bukan jenis yang benar, tetapi mengabaikan parameter yang melebihi batas. Measurement Protocol menggunakan validasi RELAXED secara default.
  • Validasi ENFORCE_RECOMMENDATIONS menolak parameter peristiwa dan item yang bukan jenis yang benar atau yang berisi parameter yang melebihi batas. Selain itu, ENFORCE_RECOMMENDATIONS menolak peristiwa atau properti pengguna apa pun dengan stempel waktu yang tidak berada dalam 72 jam terakhir.

Sebaiknya gunakan pendekatan berikut:

  • Gunakan ENFORCE_RECOMMENDATIONS saat Anda memvalidasi peristiwa untuk mendapatkan masukan sebanyak mungkin tentang potensi masalah pada permintaan Anda.

    Anda juga dapat memvalidasi permintaan menggunakan Event Builder karena alat ini menentukan ENFORCE_RECOMMENDATIONS saat memvalidasi permintaan.

  • Jangan tentukan validation_behavior saat Anda mengirim peristiwa untuk meminimalkan data yang ditolak oleh Measurement Protocol.

    Jika Anda ingin memprioritaskan validasi ketat daripada pengumpulan data saat mengirim permintaan tertentu, tambahkan kolom validation_behavior dan tetapkan ke ENFORCE_RECOMMENDATIONS.

Parameter kustom

Anda dapat menyertakan parameter kustom cakupan pengguna, cakupan peristiwa, dan cakupan item dalam payload Measurement Protocol.

  • Parameter kustom cakupan pengguna dapat disertakan dalam user_properties.
  • Parameter kustom cakupan peristiwa dapat disertakan dalam events[].params.
  • Parameter kustom cakupan item dapat disertakan dalam items.

Beberapa peristiwa memiliki parameter yang direkomendasikan. Lihat peristiwa untuk parameter yang direkomendasikan untuk semua peristiwa yang didukung.

Nama yang dicadangkan

Beberapa nama peristiwa, parameter, dan properti pengguna dicadangkan dan tidak dapat digunakan:

Nama peristiwa yang dicadangkan

Nama peristiwa berikut dicadangkan dan tidak dapat digunakan:

  • ad_activeview
  • ad_click
  • ad_exposure
  • ad_query
  • ad_reward
  • adunit_exposure
  • app_clear_data
  • app_exception
  • app_install
  • app_remove
  • app_store_refund
  • app_update
  • app_upgrade
  • dynamic_link_app_open
  • dynamic_link_app_update
  • dynamic_link_first_open
  • error
  • firebase_campaign
  • firebase_in_app_message_action
  • firebase_in_app_message_dismiss
  • firebase_in_app_message_impression
  • first_open
  • first_visit
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

Selain itu, peristiwa ad_impression, in_app_purchase, dan screen_view hanya diizinkan untuk aliran data Aplikasi.

Nama parameter yang dicadangkan

Nama parameter berikut dicadangkan dan tidak dapat digunakan:

  • firebase_conversion

Nama parameter tidak boleh diawali dengan:

  • _ (underscore)
  • firebase_
  • ga_
  • google_
  • gtag.

Nama properti pengguna yang dicadangkan

Nama properti pengguna berikut dicadangkan dan tidak dapat digunakan:

  • first_open_time
  • first_visit_time
  • last_deep_link_referrer
  • user_id
  • first_open_after_install

Selain itu, nama properti pengguna tidak boleh diawali dengan:

  • _ (underscore)
  • firebase_
  • ga_
  • google_