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

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

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

  • สําหรับสตรีมเว็บ (โดยทั่วไปจะใช้ gtag.js หรือ Google Tag Manager) คุณจะใช้ measurement_id ใน URL คำขอและ client_id ในเนื้อหา JSON เพื่อระบุอินสแตนซ์ของผู้ใช้ client_id ควรตรงกับรหัสที่สร้างโดยแท็ก Google Analytics ในเว็บไซต์
  • สําหรับสตรีมแอป (ที่ใช้ Firebase SDK) คุณจะใช้ firebase_app_id ใน URL คำขอและ app_instance_id ในเนื้อหา JSON ซึ่งได้มาจาก Google Analytics สำหรับ Firebase SDK

คู่มือนี้จะแสดงตัวอย่างสำหรับทั้ง 2 สถานการณ์

องค์ประกอบคำขอหลักตามประเภทสตรีม

ส่วนประกอบ สตรีมเว็บ (gtag.js/GTM) สตรีมแอป (Firebase)
พารามิเตอร์ของ URL สตรีมข้อมูล measurement_id firebase_app_id
พารามิเตอร์ของ URL สำหรับ API Secret ต้องระบุ ต้องระบุ
ฟิลด์เนื้อหา JSON ของรหัสอุปกรณ์ client_id app_instance_id

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

แท็บนี้แสดงวิธีการส่งเหตุการณ์จากเซิร์ฟเวอร์ที่เชื่อมโยงกับกิจกรรมของผู้ใช้ในสตรีมแอปโดยใช้ SDK ของ Google Analytics สำหรับ Firebase โปรดทราบว่าคำขอเหล่านี้ใช้ firebase_app_id และ app_instance_id

ข้อกำหนดเบื้องต้น

หากต้องการส่งเหตุการณ์โดยใช้ Measurement Protocol คุณต้องมีตัวระบุที่เฉพาะเจาะจงจากพร็อพเพอร์ตี้ Google Analytics หรือโปรเจ็กต์ Firebase

API Secret

api_secret ใช้เพื่อตรวจสอบสิทธิ์คำขอของคุณ คุณต้องเก็บข้อมูลลับนี้ไว้เป็นความลับ

วิธีสร้างข้อมูลลับใหม่

  1. ไปที่ Google Analytics แล้วไปยังบัญชีและพร็อพเพอร์ตี้ของคุณ
  2. คลิกผู้ดูแลระบบที่ด้านซ้ายล่าง
  3. ในส่วนการเก็บรวบรวมข้อมูลและการแก้ไขข้อมูล ให้คลิกสตรีมข้อมูล
  4. เลือกสตรีมข้อมูลเว็บหรือแอป
  5. คลิก API Secret สำหรับ Measurement Protocol
  6. คลิกสร้าง
  7. ป้อนชื่อเล่นสำหรับข้อมูลลับ แล้วคลิกสร้าง
  8. คัดลอกค่าข้อมูลลับ

รหัสแอป Firebase

firebase_app_id จะระบุแอป Firebase ของคุณ ซึ่งไม่เหมือนกับ app_instance_id

วิธีค้นหารหัสแอป Firebase

  1. เปิดโปรเจ็กต์ในคอนโซล Firebase
  2. คลิกไอคอนรูปเฟืองของการตั้งค่าข้างภาพรวมของโปรเจ็กต์ แล้วเลือกการตั้งค่าโปรเจ็กต์
  3. ในแท็บทั่วไป ให้ไปที่ส่วนแอปของคุณ
  4. เลือกแอป iOS หรือ Android ที่ต้องการ
  5. คัดลอกค่ารหัสแอป

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

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

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

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

คุณต้องระบุข้อมูลต่อไปนี้ในพารามิเตอร์การค้นหาของ URL ที่ขอ (ดูรายละเอียดเกี่ยวกับวิธีค้นหาหรือสร้างค่าเหล่านี้ได้ที่ข้อกำหนดเบื้องต้น)

  • api_secret: API Secret เพื่อตรวจสอบสิทธิ์คำขอ
  • firebase_app_id: รหัสแอป Firebase ของแอปพลิเคชัน

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

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

คุณต้องระบุ app_instance_id ในเนื้อหาคำขอเพื่อระบุการติดตั้งแอปบนมือถือที่ไม่ซ้ำกัน โปรดทราบว่าค่านี้แตกต่างจาก firebase_app_id ซึ่งระบุตัวแอปเอง ดูข้อมูลเพิ่มเติมเกี่ยวกับ app_instance_id และวิธีดึงข้อมูลโดยใช้ Firebase SDK ได้ที่เอกสารอ้างอิง app_instance_id

แม้ 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

  • คุณส่งคำขอที่ไม่ใช่ Conversion ได้สูงสุด 100 ล้านรายการต่อชั่วโมงสำหรับพร็อพเพอร์ตี้แต่ละรายการ คำขอจะเป็นคำขอที่ไม่ใช่ Conversion หากไม่มีเหตุการณ์ใดในคำขอเป็นเหตุการณ์สำคัญที่มี Conversion ใน Google Ads หากคุณเกินขีดจำกัดนี้ Measurement Protocol จะละเว้นคำขอที่ไม่ใช่ Conversion ทั้งหมดสำหรับพร็อพเพอร์ตี้ในช่วงเวลาที่เหลือของชั่วโมงนั้นโดยไม่มีการแจ้งเตือน

  • คำขอมีเหตุการณ์ได้สูงสุด 25 รายการ

  • เหตุการณ์มีพารามิเตอร์ได้สูงสุด 25 รายการ

  • เหตุการณ์มีพร็อพเพอร์ตี้ผู้ใช้ได้สูงสุด 25 รายการ

  • ชื่อพร็อพเพอร์ตี้ผู้ใช้ต้องมีความยาวไม่เกิน 24 อักขระ

  • ค่าพร็อพเพอร์ตี้ผู้ใช้ต้องมีความยาวไม่เกิน 36 อักขระ

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

  • ชื่อพารามิเตอร์ (เช่น พารามิเตอร์ของสินค้า) ต้องขึ้นต้นด้วยตัวอักษรและมีความยาวไม่เกิน 40 อักขระ ซึ่งจะใช้ได้เพียงอักขระที่เป็นตัวอักษรและตัวเลขคละกัน และขีดล่างเท่านั้น

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

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

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

  • เนื้อหาโพสต์ต้องมีขนาดไม่เกิน 130 kB

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

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

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

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

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

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