Mengirim peristiwa Measurement Protocol ke Google Analytics

Panduan ini menjelaskan cara mengirim peristiwa Measurement Protocol Google Analytics aliran data web dan aplikasi ke server Google Analytics, sehingga Anda dapat melihat peristiwa Measurement Protocol di laporan Google Analytics.

ID dan parameter yang diperlukan untuk permintaan Measurement Protocol bergantung pada apakah Anda mengirim peristiwa ke Aliran data web atau Aliran data aplikasi.

• Untuk Aliran web (biasanya diukur dengan gtag.js atau Google Tag Manager), Anda menggunakan measurement_id di URL permintaan dan client_id di isi JSON untuk mengidentifikasi instance pengguna. client_id harus cocok dengan ID yang dihasilkan oleh tag Google Analytics di situs Anda.
• Untuk Aliran aplikasi (yang diukur dengan Firebase SDK), Anda menggunakan firebase_app_id di URL permintaan dan app_instance_id di isi JSON, yang disediakan oleh Google Analytics for Firebase SDK.

Panduan ini memberikan contoh untuk kedua skenario tersebut.

Komponen permintaan utama menurut jenis streaming

Komponen	Aliran data web (gtag.js/GTM)	Aliran data aplikasi (Firebase)
Parameter URL aliran data	measurement_id	firebase_app_id
Parameter URL rahasia API	Wajib	Wajib
Kolom isi JSON ID perangkat	client_id	app_instance_id

Pilih platform yang ingin Anda lihat dalam panduan ini:

Firebase gtag.js

Tab ini menampilkan petunjuk untuk mengirim peristiwa dari server Anda yang berkorelasi dengan aktivitas pengguna di Aliran aplikasi menggunakan Google Analytics for Firebase SDK. Perlu diingat bahwa permintaan ini menggunakan firebase_app_id dan app_instance_id.

Prasyarat

Untuk mengirim peristiwa menggunakan Measurement Protocol, Anda memerlukan ID tertentu dari properti Google Analytics atau project Firebase Anda.

API secret

api_secret digunakan untuk mengautentikasi permintaan Anda. Rahasia ini harus dijaga kerahasiaannya.

Untuk membuat rahasia baru:

1. Buka Google Analytics, lalu buka akun dan properti Anda.
2. Klik Admin di kiri bawah.
3. Di bagian Pengumpulan dan modifikasi data, klik Aliran data.
4. Pilih aliran data Web atau Aplikasi Anda.
5. Klik Rahasia API Measurement Protocol.
6. Klik Buat.
7. Masukkan nama panggilan untuk rahasia tersebut, lalu klik Buat.

8. Salin Nilai rahasia.

   Penting: api_secret bersifat pribadi. Jangan menampilkannya di kode sisi klien situs atau aplikasi Anda.

   • Risiko keamanan: Mengekspos api_secret memungkinkan pihak yang tidak berwenang mengirim data spam atau data arbitrer ke properti Google Analytics Anda, yang dapat merusak pelaporan Anda.
   • Penggunaan yang benar: Measurement Protocol terutama dirancang untuk lingkungan sisi server atau tepercaya (seperti sistem offline atau komunikasi server-ke-server).
   • Pelacakan sisi klien: Jika Anda perlu mengirim peristiwa langsung dari browser web, gunakan Tag Google (gtag.js) atau Google Tag Manager.
   • Ekstensi Chrome: Untuk Ekstensi Chrome Manifes V3, Anda tidak dapat memuat kode jarak jauh seperti gtag.js. Dalam hal ini, Measurement Protocol adalah pendekatan yang direkomendasikan. Lihat Menggunakan Google Analytics di ekstensi Chrome.

ID Aplikasi Firebase

firebase_app_id mengidentifikasi aplikasi Firebase Anda. ID ini tidak sama dengan app_instance_id.

Untuk menemukan ID Aplikasi Firebase Anda:

1. Buka project Anda di Firebase console.
2. Klik ikon roda gigi setelan di samping Ringkasan Project, lalu pilih Setelan project.
3. Di tab Umum, buka bagian Aplikasi Anda.
4. Pilih aplikasi iOS atau Android tertentu.
5. Salin nilai App ID.

Format permintaan

Measurement Protocol Google Analytics hanya mendukung permintaan POST HTTP.

Untuk mengirim peristiwa, gunakan format berikut:

POST /mp/collect?firebase_app_id=<var>FIREBASE_APP_ID</var>&api_secret=<var>API_SECRET</var> HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

Tips: Jika Anda ingin data Anda dikumpulkan di Uni Eropa, ubah HOST dalam contoh menjadi region1.google-analytics.com.

Anda harus memberikan hal berikut dalam parameter kueri URL permintaan (lihat Prasyarat untuk mengetahui detail tentang cara menemukan atau membuat nilai-nilai ini):

• api_secret: Rahasia API untuk mengautentikasi permintaan.
• firebase_app_id: ID Aplikasi Firebase aplikasi Anda.

Anda harus memberikan isi permintaan dalam format isi POST JSON untuk Measurement Protocol. Berikut contohnya:

  {
   "app_instance_id": "APP_INSTANCE_ID",
   "events": [
      {
        "name": "login",
        "params": {
          "method": "Google",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      }
   ]
  }

Anda harus memberikan app_instance_id di isi permintaan untuk mengidentifikasi penginstalan unik aplikasi seluler Anda. Perhatikan bahwa ini berbeda dengan firebase_app_id yang mengidentifikasi aplikasi itu sendiri. Untuk mengetahui informasi selengkapnya tentang app_instance_id dan cara mengambilnya menggunakan Firebase SDK, lihat dokumentasi referensi app_instance_id.

Meskipun session_start adalah nama peristiwa yang dicadangkan, pembuatan session_id baru akan membuat sesi baru tanpa perlu mengirim session_start. Pahami cara penghitungan sesi.

Coba

Catatan: Contoh berikut menggunakan fetch API dan ditujukan untuk digunakan di lingkungan sisi server atau tepercaya (misalnya, Node.js atau server backend). Kunci ini tidak boleh digunakan dalam kode sisi klien (browser) karena akan mengekspos api_secret Anda.

Berikut contoh yang dapat Anda gunakan untuk mengirim beberapa peristiwa sekaligus. Contoh ini mengirimkan peristiwa tutorial_begin dan peristiwa join_group ke server Google Analytics Anda, menyertakan informasi geografis menggunakan kolom user_location, dan menyertakan informasi perangkat menggunakan kolom device.

const firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_ID",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 150
        }
      }
    ],
    user_location: {
      city: "Mountain View",
      region_id: "US-CA",
      country_id: "US",
      subcontinent_id: "021",
      continent_id: "019"
    },
    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"
    }
  })
});

Format firebase_app_id berbeda untuk setiap platform. Lihat ID Aplikasi di bagian Objek dan file konfigurasi Firebase

Mengganti stempel waktu

Measurement Protocol menggunakan stempel waktu pertama yang ditemukannya dalam daftar berikut untuk setiap peristiwa dan properti pengguna dalam permintaan:

1. timestamp_micros peristiwa atau properti pengguna.
2. timestamp_micros permintaan.
3. Waktu saat Measurement Protocol menerima permintaan.

Contoh berikut mengirimkan stempel waktu tingkat permintaan yang berlaku untuk semua peristiwa dan properti pengguna dalam permintaan. Akibatnya, Measurement Protocol menetapkan stempel waktu requestUnixEpochTimeInMicros ke peristiwa tutorial_begin dan join_group serta properti pengguna customer_tier.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin"
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM"
    }
  }
}

Contoh berikut mengirim stempel waktu tingkat permintaan, stempel waktu tingkat peristiwa, dan stempel waktu tingkat properti pengguna. Akibatnya, Measurement Protocol menetapkan stempel waktu berikut:

• tutorialBeginUnixEpochTimeInMicros untuk acara tutorial_begin
• customerTierUnixEpochTimeInMicros untuk properti pengguna customer_tier
• requestUnixEpochTimeInMicros untuk peristiwa join_group dan properti pengguna newsletter_reader.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM",
      "timestamp_micros": customerTierUnixEpochTimeInMicros
    },
    "newsletter_reader": {
      "value": "true"
    }
  }
}

Perilaku validasi untuk peristiwa dan properti pengguna sebelumnya

Peristiwa dan properti pengguna dapat diberi tanggal mundur hingga 72 jam. Jika nilai timestamp_micros lebih awal dari 72 jam yang lalu, Measurement Protocol menerima atau menolak peristiwa atau properti pengguna sebagai berikut:

• Jika validation_behavior tidak ditetapkan atau ditetapkan ke RELAXED, Measurement Protocol akan menerima peristiwa atau properti pengguna, tetapi mengganti stempel waktunya menjadi 72 jam yang lalu.
• Jika validation_behavior disetel ke ENFORCE_RECOMMENDATIONS, Measurement Protocol akan menolak peristiwa atau properti pengguna.

Peristiwa yang dikirim menggunakan Measurement Protocol yang dimaksudkan untuk digabungkan atau diproses bersama dengan peristiwa yang dikumpulkan oleh Google Analytics for Firebase SDK atau gtag.js harus diterima oleh Google Analytics dalam waktu 48 jam setelah stempel waktu peristiwa sisi klien asli. Peristiwa yang diterima setelah waktu ini mungkin tidak diproses seperti yang diharapkan, terutama untuk tujuan seperti atribusi konversi.

Batasan

Batasan berikut berlaku untuk mengirim peristiwa Measurement Protocol ke Google Analytics:

Catatan: Untuk mengetahui informasi tentang batasan fitur 360, lihat Google Analytics 360.

• Permintaan dapat memiliki maksimal 25 peristiwa.
• Peristiwa dapat memiliki maksimal 25 parameter.
• Peristiwa dapat memiliki maksimal 25 properti pengguna.
• Nama properti pengguna harus terdiri dari maksimal 24 karakter.
• Nilai properti pengguna harus 36 karakter atau kurang.
• Nama peristiwa harus terdiri dari maksimal 40 karakter, hanya boleh berisi karakter alfanumerik dan garis bawah, serta harus diawali dengan karakter alfabet.
• Nama parameter (termasuk parameter item) harus terdiri dari maksimal 40 karakter, hanya boleh berisi karakter alfanumerik dan garis bawah, serta harus diawali dengan karakter alfabet.

• Nilai parameter, termasuk nilai parameter item, harus terdiri dari 100 karakter atau kurang untuk properti Google Analytics standar, dan 500 karakter atau kurang untuk properti Google Analytics 360.

  Batas ini tidak berlaku untuk parameter session_id dan session_number jika nilainya diberikan oleh variabel bawaan ID Sesi Analytics dan Nomor Sesi Analytics yang sesuai di Google Tag Manager.

• Parameter item dapat memiliki maksimal 10 parameter kustom.

• Isi POST harus lebih kecil dari 130 KB.

• Peristiwa App Measurement Protocol yang dikirim ke Google Analytics tidak mengisi audiens Penelusuran di Google Ads untuk pengguna aplikasi.

• Beberapa nama peristiwa, parameter, dan properti pengguna dicadangkan dan tidak dapat digunakan. Lihat Nama yang dicadangkan untuk mengetahui detailnya.

Nama yang dicadangkan

Measurement Protocol memiliki beberapa nama yang dicadangkan yang tidak dapat digunakan untuk peristiwa, parameter, atau properti pengguna.

Nama peristiwa berikut sering kali membingungkan:

• screen_view: Peristiwa ini hanya diizinkan untuk aliran Aplikasi. Untuk aliran web, gunakan page_view.
• ad_impression: Peristiwa ini hanya diizinkan untuk aliran Aplikasi.
• in_app_purchase: Peristiwa ini hanya diizinkan untuk aliran Aplikasi. Untuk aliran web, gunakan peristiwa purchase.

Untuk persyaratan tambahan setiap kasus penggunaan, lihat kasus penggunaan umum.