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

คู่มือนี้อธิบายวิธีส่งเหตุการณ์ Measurement Protocol ของ Google Analytics ในสตรีมเว็บและแอป ไปยังเซิร์ฟเวอร์ 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 จะปฏิเสธเหตุการณ์หรือพร็อพเพอร์ตี้ผู้ใช้

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

ข้อจำกัด

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

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

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

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

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

  • เนื้อหาของโพสต์ต้องมีขนาดเล็กกว่า 130 KB

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

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

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

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

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

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