หน้านี้จะอธิบายกลไกการส่งและพารามิเตอร์ข้อมูลสำหรับ Measurement Protocol
การขนส่ง
ต้องส่งข้อมูลทั้งหมดอย่างปลอดภัยโดยใช้คำขอ HTTPS POST
ส่งคำขอไปยังปลายทางต่อไปนี้
https://www.google-analytics.com/mp/collect
หากต้องการให้ระบบรวบรวมข้อมูลในสหภาพยุโรป ให้ใช้ปลายทางต่อไปนี้แทน
https://region1.google-analytics.com/mp/collect
ตัวอย่างคำขอ POST มีดังนี้
POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
PAYLOAD_DATA
แทนที่ PAYLOAD_DATA ด้วยเพย์โหลดของคำขอ
Measurement Protocol จะแสดงรหัสสถานะ 2xx หากได้รับคำขอ HTTP Measurement Protocol จะไม่แสดงรหัสข้อผิดพลาดหากเพย์โหลดมีรูปแบบไม่ถูกต้อง หรือหากข้อมูลไม่ถูกต้องหรือไม่ได้รับการประมวลผลโดย Google Analytics
เพย์โหลด
เพย์โหลดมี 2 ส่วน ได้แก่
- พารามิเตอร์การค้นหา
- เนื้อหา
POSTของ JSON
พารามิเตอร์การค้นหา
| ชื่อพารามิเตอร์ | คำอธิบาย |
|---|---|
|
ต้องระบุ API Secret จาก UI ของ Google Analytics
ดูได้ในส่วนผู้ดูแลระบบ > สตรีมข้อมูล > เลือกสตรีมของคุณ > Measurement Protocol > สร้าง เป็นส่วนตัวสำหรับองค์กรของคุณ ควรอัปเดตเป็นประจำเพื่อหลีกเลี่ยงสแปมที่มากเกินไป |
|
ต้องระบุ รหัสแอป Firebase ตัวระบุสำหรับแอป Firebase
ดูได้ในคอนโซล Firebase ในส่วนการตั้งค่าโปรเจ็กต์ > ทั่วไป > แอปของคุณ > รหัสแอป |
เนื้อหา JSON POST
ขนาดของเนื้อหา JSON POST ต้องไม่เกิน 130 kB
| คีย์ | ประเภท | คำอธิบาย |
|---|---|---|
|
string |
ต้องระบุ ตัวระบุที่ไม่ซ้ำกันสำหรับการติดตั้งแอป Firebase ที่เฉพาะเจาะจง
ซึ่งไม่เหมือนกับ ต้องดึงข้อมูลโดยใช้ Firebase SDK: |
|
string |
ไม่บังคับ ตัวระบุที่ไม่ซ้ำกันสำหรับผู้ใช้ ดูข้อมูลเพิ่มเติมเกี่ยวกับตัวระบุนี้ได้ที่ User-ID สำหรับการวิเคราะห์ข้ามแพลตฟอร์ม มีได้เฉพาะอักขระ UTF-8 เท่านั้น |
|
number |
ไม่บังคับ การประทับเวลา Unix ในหน่วยไมโครวินาที ไม่ใช่มิลลิวินาที แสดงเวลาของเหตุการณ์ ควรตั้งค่าให้บันทึกเฉพาะเหตุการณ์ที่เกิดขึ้นในอดีตเท่านั้น ลบล้างได้โดย |
|
object |
ไม่บังคับ พร็อพเพอร์ตี้ผู้ใช้สําหรับการวัด คุณส่งพร็อพเพอร์ตี้ผู้ใช้ได้สูงสุด 25 รายการต่อคำขอ ชื่อพร็อพเพอร์ตี้ผู้ใช้ต้องมีความยาวไม่เกิน 24 อักขระ และค่าพร็อพเพอร์ตี้ผู้ใช้ต้องมีความยาวไม่เกิน 36 อักขระ |
|
object |
ไม่บังคับ ข้อมูลที่ได้จากผู้ใช้ |
|
object |
ไม่บังคับ การตั้งค่าความยินยอมสำหรับคำขอ ดูข้อมูลเพิ่มเติมได้ที่ส่วนความยินยอม |
|
boolean |
ไม่บังคับ ตั้งค่าเป็น true เพื่อระบุว่าไม่ควรใช้ข้อมูลของผู้ใช้สำหรับโฆษณาที่ปรับตามโปรไฟล์ของผู้ใช้
|
|
object |
ไม่บังคับ ตั้งค่าข้อมูลทางภูมิศาสตร์สำหรับคำขอในรูปแบบที่มีโครงสร้าง |
|
string |
ไม่บังคับ ที่อยู่ IP ที่ Google Analytics ใช้เพื่อรับข้อมูลทางภูมิศาสตร์สําหรับคําขอ |
|
object |
ไม่บังคับ ตั้งค่าข้อมูลอุปกรณ์สำหรับคำขอในรูปแบบที่มีโครงสร้าง |
|
string |
ไม่บังคับ ตั้งค่าลักษณะการตรวจสอบสำหรับคำขอ
|
|
array |
ต้องระบุ อาร์เรย์ของรายการ event รายการ คุณส่งเหตุการณ์ได้สูงสุด 25 รายการต่อคำขอ ดูข้อมูลอ้างอิงเหตุการณ์สําหรับเหตุการณ์ที่แนะนํา
|
|
string |
ต้องระบุ ชื่อเหตุการณ์ ชื่อเหตุการณ์ต้องมีอักขระไม่เกิน 40 ตัว ดูเหตุการณ์ที่แนะนําได้ที่เหตุการณ์ |
|
object |
ไม่บังคับ พารามิเตอร์สําหรับเหตุการณ์ คุณส่งพารามิเตอร์ได้สูงสุด 25 รายการต่อเหตุการณ์ ดูพารามิเตอร์ที่แนะนําสําหรับแต่ละเหตุการณ์ได้ที่เหตุการณ์ และพารามิเตอร์เหตุการณ์ทั่วไป
ชื่อพารามิเตอร์ต้องมีอักขระไม่เกิน 40 ตัว ค่าพารามิเตอร์ต้องมีอักขระไม่เกิน 100 ตัวสำหรับพร็อพเพอร์ตี้ Google Analytics มาตรฐาน และไม่เกิน 500 ตัวสำหรับพร็อพเพอร์ตี้ Google Analytics 360 |
พารามิเตอร์เหตุการณ์ทั่วไป
Measurement Protocol มีพารามิเตอร์เหตุการณ์ทั่วไปดังต่อไปนี้
| คีย์ | ประเภท | คำอธิบาย |
|---|---|---|
|
number |
ตัวเลขบวกที่ระบุเซสชันของผู้ใช้ จำเป็นสำหรับกรณีการใช้งานทั่วไปหลายกรณี
ต้องตรงกับนิพจน์ทั่วไป ^\d+$
ต้องดึงข้อมูลโดยใช้ Firebase SDK: |
|
number |
ระยะเวลาของการมีส่วนร่วมของผู้ใช้ในหน่วยมิลลิวินาทีสําหรับเหตุการณ์ ใช้ค่าที่แสดงระยะเวลาการมีส่วนร่วมของผู้ใช้นับตั้งแต่เหตุการณ์ก่อนหน้า |
|
number |
เวลา Unix Epoch ในหน่วยไมโครวินาทีสำหรับเหตุการณ์ ใช้พารามิเตอร์นี้เพื่อลบล้างการประทับเวลาของเหตุการณ์ |
ความยินยอม
แอตทริบิวต์ consent จะกำหนดค่าประเภทและสถานะความยินยอม
หากคุณไม่ระบุ consent, Google Analytics จะใช้การตั้งค่าความยินยอมจากการโต้ตอบออนไลน์ที่เกี่ยวข้องสําหรับไคลเอ็นต์หรืออินสแตนซ์แอป
| คีย์ | ประเภท | คำอธิบาย |
|---|---|---|
|
string |
ไม่บังคับ ความยินยอมในการส่งข้อมูลผู้ใช้จากเหตุการณ์และพร็อพเพอร์ตี้ผู้ใช้ของคำขอไปยัง Google เพื่อวัตถุประสงค์ในการโฆษณา
|
|
string |
ไม่บังคับ ความยินยอมสำหรับโฆษณาที่ปรับตามโปรไฟล์ของผู้ใช้
|
ข้อมูลทางภูมิศาสตร์
แอตทริบิวต์ user_location และ ip_override จะให้ข้อมูลทางภูมิศาสตร์
user_location จะมีความสำคัญเหนือ ip_override
โครงสร้างของช่อง user_location มีดังนี้ ระบุแอตทริบิวต์ให้มากที่สุดเท่าที่จะเป็นไปได้ เราขอแนะนำให้ใช้ country_id และ region_id เป็นอย่างน้อย
| คีย์ | ประเภท | คำอธิบาย |
|---|---|---|
|
string |
ไม่บังคับ ชื่อเมือง หากเมืองอยู่ในสหรัฐอเมริกา ให้ตั้งค่า country_id และ region_id ด้วยเพื่อให้ Google Analytics แมปชื่อเมืองกับรหัสเมืองได้อย่างถูกต้อง
|
|
string |
ไม่บังคับ ประเทศและพื้นที่ย่อยตามมาตรฐาน ISO 3166 เช่น US-CA, US-AR, CA-BC, GB-LND, CN-HK
|
|
string |
ไม่บังคับ ประเทศในรูปแบบ ISO 3166-1 alpha-2 เช่น US, AU, ES, FR
|
|
string |
ไม่บังคับ อนุทวีปในรูปแบบ UN M49 เช่น 011, 021, 030, 039
|
|
string |
ไม่บังคับ ทวีปในรูปแบบ UN M49 เช่น 002, 019, 142, 150
|
ตัวอย่าง user_location มีดังนี้
"user_location": {
"city": "Mountain View",
"region_id": "US-CA",
"country_id": "US",
"subcontinent_id": "021",
"continent_id": "019"
}
ip_override เป็นทางเลือกแทน user_location หากคุณส่ง ip_override แทน Google Analytics จะดึงข้อมูลทางภูมิศาสตร์จากที่อยู่ IP
หากคุณส่ง user_location, Google Analytics จะละเว้น ip_override
หากคุณไม่ส่ง user_location หรือ ip_override, Google Analytics จะดึงข้อมูลทางภูมิศาสตร์จากการติดแท็กเหตุการณ์โดยใช้app_instance_id
Google Analytics จะใช้การตั้งค่าข้อมูลตำแหน่งแบบละเอียดของพร็อพเพอร์ตี้กับคำขอ ไม่ว่าจะส่งข้อมูลทางภูมิศาสตร์ใดก็ตาม
ข้อมูลอุปกรณ์
หากต้องการส่งข้อมูลอุปกรณ์ ให้ใช้ช่อง device โครงสร้างของช่อง device มีดังนี้ ระบุแอตทริบิวต์ให้มากที่สุดเท่าที่จะเป็นไปได้ เราขอแนะนำให้ใช้ category เป็นอย่างน้อย
| คีย์ | ประเภท | คำอธิบาย |
|---|---|---|
|
string |
ไม่บังคับ หมวดหมู่ของอุปกรณ์ เช่น
desktop
tablet
mobile
smart TV
|
|
string |
ไม่บังคับ ภาษาในรูปแบบ ISO 639-1 เช่น en, en-US
|
|
string |
ไม่บังคับ ความละเอียดของอุปกรณ์ในรูปแบบ WIDTHxHEIGHT เช่น 1280x2856, 1080x2340
|
|
string |
ไม่บังคับ ระบบปฏิบัติการหรือแพลตฟอร์ม เช่น MacOS
|
|
string |
ไม่บังคับ เวอร์ชันของระบบปฏิบัติการหรือแพลตฟอร์ม เช่น 13.5
|
|
string |
ไม่บังคับ รุ่นของอุปกรณ์ เช่น Pixel 9 Pro, Samsung Galaxy S24
|
|
string |
ไม่บังคับ แบรนด์ของอุปกรณ์ เช่น Google, Samsung
|
|
string |
ไม่บังคับ แบรนด์หรือประเภทของเบราว์เซอร์ เช่น Chrome, Firefox
|
|
string |
ไม่บังคับ เวอร์ชันของเบราว์เซอร์ เช่น 136.0.7103.60, 5.0
|
ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างการตั้งค่า device
"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"
}
device Google Analytics จะดึงข้อมูลอุปกรณ์จากเหตุการณ์การติดแท็กโดยใช้ app_instance_id
ไม่ว่าคุณจะระบุdeviceGoogle Analytics จะใช้การตั้งค่าข้อมูลอุปกรณ์แบบละเอียดของพร็อพเพอร์ตี้กับคำขอ
ลักษณะการทำงานของการตรวจสอบความถูกต้อง
แอตทริบิวต์ validation_behavior จะควบคุมวิธีที่ Measurement Protocol ตรวจสอบเนื้อหาของคำขอ
- การตรวจสอบ
RELAXEDจะปฏิเสธเฉพาะคำขอที่มีรูปแบบไม่ถูกต้อง ระบบอาจยังคงยอมรับเหตุการณ์และพารามิเตอร์ที่มีชื่อช่องที่ไม่ถูกต้องหรือมีข้อมูลที่ไม่ใช่ประเภทที่ถูกต้อง แต่จะละเว้นพารามิเตอร์ที่เกินขีดจํากัด Measurement Protocol ใช้การตรวจสอบRELAXEDโดยค่าเริ่มต้น - การตรวจสอบความถูกต้องของ
ENFORCE_RECOMMENDATIONSจะปฏิเสธพารามิเตอร์เหตุการณ์และสินค้าที่ไม่ใช่ประเภทที่ถูกต้อง หรือมีพารามิเตอร์ที่เกินขีดจำกัด นอกจากนี้ENFORCE_RECOMMENDATIONSจะปฏิเสธเหตุการณ์หรือพร็อพเพอร์ตี้ผู้ใช้ที่มีการประทับเวลาที่ไม่ได้อยู่ในช่วง 72 ชั่วโมงที่ผ่านมา
เราขอแนะนำให้ใช้วิธีการต่อไปนี้
ใช้
ENFORCE_RECOMMENDATIONSเมื่อคุณตรวจสอบเหตุการณ์เพื่อรับความคิดเห็นเกี่ยวกับปัญหาที่อาจเกิดขึ้นกับคำขอของคุณให้ได้มากที่สุดนอกจากนี้ คุณยังตรวจสอบคำขอโดยใช้เครื่องมือสร้างเหตุการณ์ได้ด้วย เนื่องจากเครื่องมือนี้จะระบุ
ENFORCE_RECOMMENDATIONSเมื่อตรวจสอบคำขออย่าระบุ
validation_behaviorเมื่อคุณส่งเหตุการณ์เพื่อลดข้อมูลที่ Measurement Protocol ปฏิเสธหากต้องการให้ความสำคัญกับการตรวจสอบที่เข้มงวดมากกว่าการเก็บรวบรวมข้อมูลเมื่อส่งคำขอหนึ่งๆ ให้เพิ่มช่อง
validation_behaviorและตั้งค่าเป็นENFORCE_RECOMMENDATIONS
พารามิเตอร์ที่กำหนดเอง
คุณสามารถรวมพารามิเตอร์ที่กําหนดเองระดับผู้ใช้ ระดับเหตุการณ์ และระดับสินค้าไว้ในเพย์โหลด Measurement Protocol ได้
- พารามิเตอร์ที่กำหนดเองระดับผู้ใช้สามารถรวมอยู่ใน
user_propertiesได้ - พารามิเตอร์ที่กําหนดเองระดับเหตุการณ์สามารถรวมอยู่ใน
events[].paramsได้ - พารามิเตอร์ที่กำหนดเองระดับสินค้าสามารถรวมอยู่ใน
items
ค่าที่แนะนําสําหรับบางเหตุการณ์
บางเหตุการณ์มีพารามิเตอร์ที่แนะนํา ดูเหตุการณ์สําหรับพารามิเตอร์ที่แนะนําสําหรับเหตุการณ์ที่รองรับทั้งหมด
ชื่อที่สงวนไว้
ชื่อเหตุการณ์ พารามิเตอร์ และพร็อพเพอร์ตี้ผู้ใช้บางชื่อเป็นชื่อที่สงวนไว้และไม่สามารถใช้ได้ ดังนี้
ชื่อเหตุการณ์ที่สงวนไว้
ชื่อเหตุการณ์ต่อไปนี้เป็นชื่อที่สงวนไว้และไม่สามารถใช้ได้
ad_activeviewad_clickad_exposuread_queryad_rewardadunit_exposureapp_clear_dataapp_exceptionapp_installapp_removeapp_store_refundapp_updateapp_upgradedynamic_link_app_opendynamic_link_app_updatedynamic_link_first_openerrorfirebase_campaignfirebase_in_app_message_actionfirebase_in_app_message_dismissfirebase_in_app_message_impressionfirst_openfirst_visitnotification_dismissnotification_foregroundnotification_opennotification_receivenotification_sendos_updatesession_startuser_engagement
นอกจากนี้ เหตุการณ์ ad_impression, in_app_purchase และ screen_view ยังอนุญาตให้ใช้กับสตรีมแอปเท่านั้น
ชื่อพารามิเตอร์ที่สงวนไว้
ชื่อพารามิเตอร์ต่อไปนี้เป็นชื่อที่สงวนไว้และไม่สามารถใช้ได้
firebase_conversion
ชื่อพารามิเตอร์ต้องไม่ขึ้นต้นด้วยรายการต่อไปนี้
_ (underscore)firebase_ga_google_gtag.
ชื่อพร็อพเพอร์ตี้ผู้ใช้ที่สงวนไว้
ชื่อพร็อพเพอร์ตี้ผู้ใช้ต่อไปนี้เป็นชื่อที่สงวนไว้และไม่สามารถใช้ได้
first_open_timefirst_visit_timelast_deep_link_referreruser_idfirst_open_after_install
นอกจากนี้ ชื่อพร็อพเพอร์ตี้ผู้ใช้ต้องไม่ขึ้นต้นด้วย
_ (underscore)firebase_ga_google_