ส่งเหตุการณ์ 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 ที่สร้างขึ้นใน UI ของ Google Analytics

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

  • measurement_id: รหัสการวัดที่เชื่อมโยงกับสตรีม โดยดูได้ใน UI ของ Google Analytics ในส่วนผู้ดูแลระบบ > สตรีมข้อมูล > เลือกสตรีม > รหัสการวัด

    measurement_id ไม่ใช่รหัสสตรีม

ดูข้อมูลอ้างอิงทั้งหมดได้ที่พารามิเตอร์การค้นหา

คุณต้องป้อนข้อมูลต่อไปนี้ในเนื้อหาคำขอ

  • client_id: ตัวระบุที่ไม่ซ้ำกันสำหรับไคลเอ็นต์ ซึ่งแตกต่างจาก Firebase app_instance_id ใช้ gtag.js('get')

  • user_id: ไม่บังคับ ตัวระบุที่ไม่ซ้ำกันสำหรับผู้ใช้ ซึ่งมีได้เฉพาะอักขระ UTF-8 ดูข้อมูลเพิ่มเติมเกี่ยวกับตัวระบุนี้ได้ที่User-ID สําหรับการวิเคราะห์ข้ามแพลตฟอร์ม

  • consent: ไม่บังคับ ดูวิธีตั้งการตั้งค่าความยินยอม

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

  • events: อาร์เรย์รายการเหตุการณ์ คุณใส่หลายเหตุการณ์ในคำขอเดียวได้

    หากต้องการให้กิจกรรมของผู้ใช้แสดงในรายงาน เช่น แบบเรียลไทม์ ต้องระบุengagement_time_msecและ session_id เป็นส่วนหนึ่งของparamsสําหรับ event พารามิเตอร์ engagement_time_msec ควรแสดงเวลาในการมีส่วนร่วมของเหตุการณ์เป็นมิลลิวินาที

    เช่น

  {
   "client_id": "123456.7654321",
   "events": [
     {
        "name": "campaign_details",
        "params": {
          "campaign_id": "google_1234",
          "campaign": "Summer_fun",
          "source": "google",
          "medium": "cpc",
          "term": "summer+travel",
          "content": "logolink",
          "session_id": "123",
          "engagement_time_msec": 100
        }
     }
   ]
  }

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

ลองใช้

ต่อไปนี้คือตัวอย่างที่คุณสามารถใช้เพื่อส่งเหตุการณ์หลายรายการพร้อมกัน ตัวอย่างนี้จะส่งเหตุการณ์ tutorial_begin และเหตุการณ์ join_group ไปยังเซิร์ฟเวอร์ Google Analytics

const measurement_id = `G-XXXXXXXXXX`;
const api_secret = `<secret_value>`;

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: "XXXXXXXXXX.YYYYYYYYYY",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "123",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "123",
          "engagement_time_msec": 150
        }
      }
    ]
  })
});

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

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

  1. timestamp_micros ของเหตุการณ์
  2. timestamp_micros ของคำขอ
  3. เวลาที่ Measurement Protocol ได้รับคําขอ

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

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

ตัวอย่างต่อไปนี้จะส่งทั้งการประทับเวลาระดับคําขอและการประทับเวลาระดับเหตุการณ์ ด้วยเหตุนี้ Measurement Protocol จึงกําหนดการประทับเวลาของเหตุการณ์ tutorial_begin เป็น tutorialBeginUnixEpochTimeInMicros และเหตุการณ์ join_group เป็น requestUnixEpochTimeInMicros

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ]
}

ข้อจำกัด

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

  • คำขอมีเหตุการณ์ได้สูงสุด 25 รายการ
  • เหตุการณ์มีพารามิเตอร์ได้สูงสุด 25 รายการ
  • เหตุการณ์มีพร็อพเพอร์ตี้ผู้ใช้ได้สูงสุด 25 รายการ
  • ชื่อพร็อพเพอร์ตี้ผู้ใช้ต้องมีความยาวไม่เกิน 24 อักขระ
  • ค่าพร็อพเพอร์ตี้ผู้ใช้ต้องมีความยาวไม่เกิน 36 อักขระ
  • ชื่อเหตุการณ์ต้องขึ้นต้นด้วยตัวอักษรและมีความยาวไม่เกิน 40 อักขระ ซึ่งจะใช้ได้เพียงตัวอักษร ตัวเลข และขีดล่างเท่านั้น
  • ชื่อพารามิเตอร์ รวมถึงพารามิเตอร์ของสินค้าต้องขึ้นต้นด้วยตัวอักษรและมีความยาวไม่เกิน 40 อักขระ ซึ่งจะใช้ได้เพียงตัวอักษร ตัวเลข และขีดล่างเท่านั้น
  • ค่าพารามิเตอร์ รวมถึงค่าพารามิเตอร์ของสินค้าต้องมีความยาวไม่เกิน 100 อักขระสําหรับพร็อพเพอร์ตี้ Google Analytics มาตรฐาน และไม่เกิน 500 อักขระสําหรับพร็อพเพอร์ตี้ Google Analytics 360
  • พารามิเตอร์รายการมีพารามิเตอร์ที่กำหนดเองได้สูงสุด 10 รายการ
  • เนื้อความของโพสต์ต้องมีขนาดไม่เกิน 130 KB
  • เหตุการณ์ Measurement Protocol ของแอปที่ส่งไปยัง Google Analytics จะไม่สร้างกลุ่มเป้าหมาย Search ใน Google Ads สําหรับผู้ใช้แอป

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