Mengirim peristiwa Measurement Protocol ke Google Analytics

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

Pilih platform yang ingin Anda lihat dalam panduan ini:

Format permintaan

Measurement Protocol Google Analytics hanya mendukung permintaan POST HTTP.

Untuk mengirim peristiwa, gunakan format berikut:

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

PAYLOAD_DATA

Anda harus menyediakan hal berikut dalam URL permintaan:

  • api_secret: RAHASIA API yang dibuat di UI Google Analytics.

    Untuk membuat secret baru, buka Admin > Pengumpulan dan modifikasi data > Aliran data > pilih aliran data Anda > Secret API Measurement Protocol > Buat.

  • firebase_app_id: ID Aplikasi Firebase, yang ditemukan di Firebase console pada bagian Project Settings > General > Your Apps > App ID.

    firebase_app_id tidak sama dengan app_instance_id. firebase_app_id mengidentifikasi aplikasi Anda, sedangkan app_instance_id mengidentifikasi satu penginstalan aplikasi.

Anda harus menyediakan 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
        }
      }
   ]
  }

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

Berikut contoh yang dapat Anda gunakan untuk mengirim beberapa peristiwa sekaligus. Contoh ini mengirim 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 mengirim 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 peristiwa 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 diundur hingga 72 jam. Jika nilai timestamp_micros lebih awal dari 72 jam yang lalu, Measurement Protocol akan 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 ditetapkan 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 dari 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:

  • 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 berisi maksimal 100 karakter untuk properti Google Analytics standar, dan maksimal 500 karakter 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 Measurement Protocol Aplikasi 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 adalah poin umum yang membingungkan:

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