คู่มือนี้อธิบายวิธีส่งเหตุการณ์สตรีมเว็บและแอปของ 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 ใช้เพื่อตรวจสอบสิทธิ์คำขอของคุณ คุณต้องเก็บข้อมูลลับนี้ไว้เป็นความลับ
วิธีสร้างข้อมูลลับใหม่
- ไปที่ Google Analytics แล้วไปยังบัญชีและพร็อพเพอร์ตี้ของคุณ
- คลิกผู้ดูแลระบบที่ด้านซ้ายล่าง
- ในส่วนการเก็บรวบรวมข้อมูลและการแก้ไขข้อมูล ให้คลิกสตรีมข้อมูล
- เลือกสตรีมข้อมูลเว็บหรือแอป
- คลิก API Secret สำหรับ Measurement Protocol
- คลิกสร้าง
- ป้อนชื่อเล่นสำหรับข้อมูลลับ แล้วคลิกสร้าง
คัดลอกค่าข้อมูลลับ
รหัสแอป Firebase
firebase_app_id จะระบุแอป Firebase ของคุณ ซึ่งไม่เหมือนกับ app_instance_id
วิธีค้นหารหัสแอป Firebase
- เปิดโปรเจ็กต์ในคอนโซล Firebase
- คลิกไอคอนรูปเฟืองของการตั้งค่าข้างภาพรวมของโปรเจ็กต์ แล้วเลือกการตั้งค่าโปรเจ็กต์
- ในแท็บทั่วไป ให้ไปที่ส่วนแอปของคุณ
- เลือกแอป iOS หรือ Android ที่ต้องการ
- คัดลอกค่ารหัสแอป
จัดรูปแบบคำขอ
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 จะใช้การประทับเวลาแรกที่พบในรายการต่อไปนี้สำหรับเหตุการณ์และพร็อพเพอร์ตี้ผู้ใช้แต่ละรายการในคำขอ
timestamp_microsของเหตุการณ์หรือพร็อพเพอร์ตี้ผู้ใช้timestamp_microsของคำขอ- เวลาที่ 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_begincustomerTierUnixEpochTimeInMicrosสำหรับพร็อพเพอร์ตี้ผู้ใช้customer_tierrequestUnixEpochTimeInMicrosสำหรับเหตุการณ์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หรือตั้งค่าเป็นRELAXEDMeasurement Protocol จะยอมรับเหตุการณ์หรือพร็อพเพอร์ตี้ผู้ใช้ แต่จะลบล้างการประทับเวลาเป็น 72 ชั่วโมงที่ผ่านมา - หากตั้งค่า
validation_behaviorเป็นENFORCE_RECOMMENDATIONSMeasurement 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 มีชื่อที่สงวนไว้หลายชื่อซึ่งไม่สามารถใช้กับเหตุการณ์ พารามิเตอร์ หรือพร็อพเพอร์ตี้ผู้ใช้ได้
ชื่อเหตุการณ์ต่อไปนี้เป็นชื่อที่มักทำให้เกิดความสับสน
screen_view: เหตุการณ์นี้อนุญาตให้ใช้กับสตรีมแอปเท่านั้น สําหรับสตรีมเว็บ ให้ใช้page_viewแทนad_impression: เหตุการณ์นี้อนุญาตให้ใช้กับสตรีมแอปเท่านั้นin_app_purchase: เหตุการณ์นี้อนุญาตให้ใช้กับสตรีมแอปเท่านั้น สําหรับสตรีมเว็บ ให้ใช้เหตุการณ์purchaseแทน
ดูข้อกำหนดเพิ่มเติมของ Use Case แต่ละรายการได้ที่กรณีการใช้งานทั่วไป