ส่งเหตุการณ์ Measurement Protocol ไปยัง Google Analytics

คู่มือนี้อธิบายวิธีส่ง เหตุการณ์สตรีมเว็บและแอปของ Google Analytics Measurement Protocol ไปยัง เซิร์ฟเวอร์ Google Analytics เพื่อให้คุณดูเหตุการณ์ Measurement Protocol ใน รายงาน Google Analytics ได้

เลือกแพลตฟอร์มที่ต้องการดูในคู่มือนี้

จัดรูปแบบคำขอ

Measurement Protocol ของ Google Analytics รองรับเฉพาะคำขอ HTTP POST

หากต้องการส่งเหตุการณ์ ให้ใช้รูปแบบต่อไปนี้

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

PAYLOAD_DATA

คุณต้องป้อนข้อมูลต่อไปนี้ใน URL ที่ขอ

  • api_secret: API SECRET สร้างใน Google Analytics UI

    หากต้องการสร้างข้อมูลลับใหม่ ให้ไปที่ผู้ดูแลระบบ > การเก็บรวบรวมและการแก้ไขข้อมูล > สตรีมข้อมูล > เลือกสตรีมของคุณ > ข้อมูลลับของ Measurement Protocol API > สร้าง

  • firebase_app_id: รหัสแอป Firebase ซึ่งดูได้ในคอนโซล Firebase ที่การตั้งค่าโปรเจ็กต์ > ทั่วไป > แอปของคุณ > รหัสแอป

    firebase_app_id ไม่เหมือนกับ app_instance_id firebase_app_id ระบุแอปของคุณ ส่วน app_instance_id ระบุการติดตั้งแอปครั้งเดียว

คุณต้องระบุเนื้อหาของคำขอในรูปแบบเนื้อหา JSON POST สำหรับ Measurement Protocol ตัวอย่าง

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

แม้ session_start จะเป็น ชื่อเหตุการณ์ที่สงวนไว้ แต่การสร้าง session_id ใหม่เป็นการสร้างเซสชันใหม่โดยไม่ต้องส่ง session_start ทำความเข้าใจวิธีคํานวณเซสชัน

ลองใช้

ตัวอย่างที่คุณใช้ส่งเหตุการณ์หลายรายการพร้อมกันได้ ตัวอย่างนี้ จะส่งเหตุการณ์ tutorial_begin และเหตุการณ์ join_group ไปยังเซิร์ฟเวอร์ Google Analytics รวมถึงข้อมูลทางภูมิศาสตร์โดยใช้ช่อง user_location และข้อมูลอุปกรณ์ โดยใช้ช่อง 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"
    }
  })
});

รูปแบบของ firebase_app_id จะขึ้นอยู่กับแพลตฟอร์ม ดูรหัสแอปพลิเคชัน ในไฟล์และออบเจ็กต์การกำหนดค่า Firebase

ลบล้างการประทับเวลา

Measurement Protocol จะใช้การประทับเวลา แรก ที่พบในรายการต่อไปนี้สำหรับเหตุการณ์และพร็อพเพอร์ตี้ผู้ใช้แต่ละรายการในคำขอ

  1. timestamp_micros ของเหตุการณ์หรือพร็อพเพอร์ตี้ผู้ใช้
  2. timestamp_micros ของคำขอ
  3. เวลาที่ Measurement Protocol ได้รับคำขอ

ตัวอย่างต่อไปนี้จะส่งการประทับเวลาระดับคำขอซึ่งใช้กับเหตุการณ์และ พร็อพเพอร์ตี้ผู้ใช้ทั้งหมดในคำขอ ด้วยเหตุนี้ Measurement Protocol จึงกำหนดการประทับเวลา requestUnixEpochTimeInMicros ให้กับเหตุการณ์ tutorial_begin และ join_group รวมถึงพร็อพเพอร์ตี้ผู้ใช้ customer_tier

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

ตัวอย่างต่อไปนี้จะส่งการประทับเวลาระดับคำขอ การประทับเวลาระดับเหตุการณ์ และการประทับเวลาระดับพร็อพเพอร์ตี้ผู้ใช้ ด้วยเหตุนี้ Measurement Protocol จึงกำหนดการประทับเวลาต่อไปนี้

  • tutorialBeginUnixEpochTimeInMicros สำหรับเหตุการณ์ tutorial_begin
  • customerTierUnixEpochTimeInMicros สำหรับพร็อพเพอร์ตี้ผู้ใช้ customer_tier
  • requestUnixEpochTimeInMicros สำหรับเหตุการณ์ join_group และพร็อพเพอร์ตี้ผู้ใช้ 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"
    }
  }
}

ลักษณะการทำงานของการตรวจสอบสำหรับเหตุการณ์และพร็อพเพอร์ตี้ผู้ใช้ที่ผ่านมา

คุณสามารถกำหนดวันที่ย้อนหลังให้กับเหตุการณ์และพร็อพเพอร์ตี้ผู้ใช้ได้ไม่เกิน 72 ชั่วโมง หากค่า timestamp_micros เก่ากว่า 72 ชั่วโมงที่ผ่านมา Measurement Protocol จะยอมรับหรือปฏิเสธเหตุการณ์หรือพร็อพเพอร์ตี้ผู้ใช้ดังนี้

  • หากไม่ได้ตั้งค่า validation_behavior หรือตั้งค่าเป็น RELAXED Measurement Protocol จะยอมรับเหตุการณ์หรือพร็อพเพอร์ตี้ผู้ใช้ แต่จะลบล้างการประทับเวลาเป็น 72 ชั่วโมงที่ผ่านมา
  • หากตั้งค่า validation_behavior เป็น ENFORCE_RECOMMENDATIONS Measurement Protocol จะปฏิเสธเหตุการณ์หรือพร็อพเพอร์ตี้ผู้ใช้

Google Analytics ควรได้รับเหตุการณ์ที่ส่งโดยใช้ Measurement Protocol ซึ่งมีไว้เพื่อเข้าร่วมหรือประมวลผลร่วมกับเหตุการณ์ที่เก็บรวบรวมโดย Google Analytics สำหรับ Firebase SDK หรือ gtag.js ภายใน 48 ชั่วโมง นับจากการประทับเวลาเหตุการณ์ฝั่งไคลเอ็นต์เดิม ระบบอาจไม่ประมวลผลเหตุการณ์ที่ได้รับหลังจากนี้ตามที่คาดไว้ โดยเฉพาะอย่างยิ่งสำหรับวัตถุประสงค์ต่างๆ เช่น การระบุแหล่งที่มาของ Conversion

ข้อจำกัด

ข้อจำกัดต่อไปนี้มีผลกับการส่งเหตุการณ์ Measurement Protocol ไปยัง Google Analytics

  • คำขอมีเหตุการณ์ได้สูงสุด 25 รายการ
  • เหตุการณ์มีพารามิเตอร์ได้สูงสุด 25 รายการ
  • เหตุการณ์มีพร็อพเพอร์ตี้ผู้ใช้ได้สูงสุด 25 รายการ
  • ชื่อพร็อพเพอร์ตี้ผู้ใช้ต้องมีความยาวไม่เกิน 24 อักขระ
  • ค่าพร็อพเพอร์ตี้ผู้ใช้ต้องมีความยาวไม่เกิน 36 อักขระ
  • ชื่อเหตุการณ์ต้องขึ้นต้นด้วยตัวอักษรและมีความยาวไม่เกิน 40 อักขระ ซึ่งจะใช้ได้เพียงตัวอักษร ตัวเลข และขีดล่างเท่านั้น
  • ชื่อพารามิเตอร์ (เช่น พารามิเตอร์ของสินค้า) ต้องขึ้นต้นด้วยตัวอักษรและมีความยาวไม่เกิน 40 อักขระ ซึ่งจะใช้ได้เพียงตัวอักษร ตัวเลข และขีดล่างเท่านั้น

  • ค่าพารามิเตอร์ (เช่น ค่าพารามิเตอร์ของสินค้า) ต้องมีความยาวไม่เกิน 100 อักขระสำหรับพร็อพเพอร์ตี้ Google Analytics มาตรฐาน และไม่เกิน 500 อักขระสำหรับพร็อพเพอร์ตี้ Google Analytics 360

    ขีดจำกัดนี้ไม่มีผลกับพารามิเตอร์ session_id และ session_number เมื่อค่าของพารามิเตอร์มาจากตัวแปรในตัวของรหัสเซสชัน Google Analytics และหมายเลขเซสชัน Google Analytics ที่เกี่ยวข้องใน Google Tag Manager

  • พารามิเตอร์ของสินค้ามีพารามิเตอร์ที่กำหนดเองได้สูงสุด 10 รายการ

  • เนื้อหาของคำขอ POST ต้องมีขนาดไม่เกิน 130 KB

  • เหตุการณ์ App Measurement Protocol ที่ส่งไปยัง Google Analytics จะไม่ป้อนข้อมูลกลุ่มเป้าหมายการค้นหาใน Google Ads สำหรับผู้ใช้แอป

  • ชื่อเหตุการณ์ พารามิเตอร์ และพร็อพเพอร์ตี้ผู้ใช้บางรายการเป็นชื่อที่สงวนไว้และใช้ไม่ได้ ดูรายละเอียดได้ที่ชื่อที่สงวนไว้สำหรับ

ชื่อที่สงวนไว้

Measurement Protocol มีชื่อที่สงวนไว้หลายชื่อซึ่ง ใช้กับเหตุการณ์ พารามิเตอร์ หรือพร็อพเพอร์ตี้ผู้ใช้ไม่ได้

ชื่อเหตุการณ์ต่อไปนี้เป็นจุดที่มักทำให้เกิดความสับสน

ดูข้อกำหนดเพิ่มเติมของ Use Case แต่ละรายการได้ที่ Use Case ทั่วไป