ส่งเหตุการณ์ 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 ซึ่งได้รับจาก SDK ของ Google Analytics สําหรับ Firebase

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

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

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

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

Firebase gtag.js

แท็บนี้แสดงวิธีการส่งเหตุการณ์จากเซิร์ฟเวอร์ที่สัมพันธ์กับกิจกรรมของผู้ใช้ในสตรีมแอปโดยใช้ 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. คัดลอกค่าข้อมูลลับ

   สำคัญ: api_secret จะเป็นแบบส่วนตัว อย่านำไปแสดงในโค้ดฝั่งไคลเอ็นต์ของเว็บไซต์หรือแอป

   • ความเสี่ยงด้านความปลอดภัย: การเปิดเผย api_secret จะทําให้บุคคลที่ไม่ได้รับอนุญาต ส่งข้อมูลที่กําหนดเองหรือสแปมไปยังพร็อพเพอร์ตี้ Google Analytics ของคุณ ซึ่งอาจทําให้การรายงานเสียหายได้
   • การใช้งานที่ถูกต้อง: Measurement Protocol ออกแบบมาสําหรับสภาพแวดล้อมฝั่งเซิร์ฟเวอร์หรือสภาพแวดล้อมที่เชื่อถือได้ (เช่น ระบบออฟไลน์หรือการสื่อสารแบบ เซิร์ฟเวอร์ต่อเซิร์ฟเวอร์) เป็นหลัก
   • การติดตามฝั่งไคลเอ็นต์: หากต้องการส่งเหตุการณ์จากเว็บเบราว์เซอร์โดยตรง ให้ใช้แท็ก Google (gtag.js) หรือ Google Tag Manager
   • ส่วนขยาย Chrome: สำหรับส่วนขยาย Chrome ที่ใช้ Manifest V3 คุณจะโหลดโค้ดจากระยะไกล เช่น gtag.js ไม่ได้ ในกรณีนี้ Measurement Protocol เป็นแนวทางที่แนะนํา ดูใช้ Google Analytics ในส่วนขยาย Chrome

รหัสแอป Firebase

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

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

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

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

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

เคล็ดลับ: หากต้องการให้เก็บรวบรวมข้อมูลในสหภาพยุโรป ให้เปลี่ยน HOST ใน ตัวอย่างเป็น region1.google-analytics.com

คุณต้องระบุข้อมูลต่อไปนี้ในพารามิเตอร์การค้นหาของ 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 ทําความเข้าใจวิธีนับเซสชัน

ลองใช้

หมายเหตุ: ตัวอย่างต่อไปนี้ใช้ fetch API และมีไว้สำหรับใช้ใน ฝั่งเซิร์ฟเวอร์หรือสภาพแวดล้อมที่เชื่อถือได้ (เช่น Node.js หรือเซิร์ฟเวอร์ แบ็กเอนด์) ไม่ควรใช้ในโค้ดฝั่งไคลเอ็นต์ (เบราว์เซอร์) เนื่องจากจะทำให้api_secret

ของคุณเปิดเผย

ต่อไปนี้คือตัวอย่างที่คุณใช้ส่งเหตุการณ์หลายรายการพร้อมกันได้ ตัวอย่างนี้ จะส่งเหตุการณ์ 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 ใช้การประทับเวลา first ที่พบในรายการต่อไปนี้ สําหรับแต่ละเหตุการณ์และพร็อพเพอร์ตี้ผู้ใช้ในคําขอ

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

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

ข้อจำกัด

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

หมายเหตุ: ดูข้อมูลเกี่ยวกับข้อจำกัดของฟีเจอร์ 360 ได้ที่ Google Analytics 360

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

  ประเด็นสำคัญ: ขีดจำกัดนี้ไม่มีผลกับพร็อพเพอร์ตี้ Google Analytics 360

• คำขอมีเหตุการณ์ได้สูงสุด 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 มีชื่อที่สงวนไว้หลายชื่อซึ่ง ใช้กับเหตุการณ์ พารามิเตอร์ หรือพร็อพเพอร์ตี้ผู้ใช้ไม่ได้

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

• screen_view: เหตุการณ์นี้อนุญาตเฉพาะสตรีมแอป สำหรับสตรีมบนเว็บ ให้ใช้ page_view แทน
• ad_impression: เหตุการณ์นี้อนุญาตเฉพาะสตรีมแอป
• in_app_purchase: เหตุการณ์นี้อนุญาตเฉพาะสตรีมแอป สําหรับสตรีมเว็บ ให้ใช้เหตุการณ์ purchase แทน

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