การอ้างอิง Measurement Protocol

หน้านี้จะอธิบายกลไกการส่งและพารามิเตอร์ข้อมูลสำหรับ 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 ส่วน ได้แก่

  1. พารามิเตอร์การค้นหา
  2. เนื้อหา POST ของ JSON

พารามิเตอร์การค้นหา

ชื่อพารามิเตอร์ คำอธิบาย

api_secret

ต้องระบุ API Secret จาก UI ของ Google Analytics

ดูได้ในส่วนผู้ดูแลระบบ > สตรีมข้อมูล > เลือกสตรีมของคุณ > Measurement Protocol > สร้าง

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

firebase_app_id

ต้องระบุ รหัสแอป Firebase ตัวระบุสำหรับแอป Firebase

ดูได้ในคอนโซล Firebase ในส่วนการตั้งค่าโปรเจ็กต์ > ทั่วไป > แอปของคุณ > รหัสแอป

เนื้อหา JSON POST

ขนาดของเนื้อหา JSON POST ต้องไม่เกิน 130 kB

คีย์ ประเภท คำอธิบาย

app_instance_id

string ต้องระบุ ตัวระบุที่ไม่ซ้ำกันสำหรับการติดตั้งแอป Firebase ที่เฉพาะเจาะจง

ซึ่งไม่เหมือนกับ client_id ของเว็บ

ต้องดึงข้อมูลโดยใช้ Firebase SDK:

user_id

string

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

timestamp_micros

number

ไม่บังคับ การประทับเวลา Unix ในหน่วยไมโครวินาที ไม่ใช่มิลลิวินาที แสดงเวลาของเหตุการณ์ ควรตั้งค่าให้บันทึกเฉพาะเหตุการณ์ที่เกิดขึ้นในอดีตเท่านั้น ลบล้างได้โดย user_property หรือการประทับเวลาของเหตุการณ์ เหตุการณ์สามารถย้อนหลังได้สูงสุด 72 ชั่วโมง

user_properties

object ไม่บังคับ พร็อพเพอร์ตี้ผู้ใช้สําหรับการวัด คุณส่งพร็อพเพอร์ตี้ผู้ใช้ได้สูงสุด 25 รายการต่อคำขอ ชื่อพร็อพเพอร์ตี้ผู้ใช้ต้องมีความยาวไม่เกิน 24 อักขระ และค่าพร็อพเพอร์ตี้ผู้ใช้ต้องมีความยาวไม่เกิน 36 อักขระ

user_data

object ไม่บังคับ ข้อมูลที่ได้จากผู้ใช้
object ไม่บังคับ การตั้งค่าความยินยอมสำหรับคำขอ ดูข้อมูลเพิ่มเติมได้ที่ส่วนความยินยอม

non_personalized_ads

boolean ไม่บังคับ ตั้งค่าเป็น true เพื่อระบุว่าไม่ควรใช้ข้อมูลของผู้ใช้สำหรับโฆษณาที่ปรับตามโปรไฟล์ของผู้ใช้

user_location

object ไม่บังคับ ตั้งค่าข้อมูลทางภูมิศาสตร์สำหรับคำขอในรูปแบบที่มีโครงสร้าง

ip_override

string ไม่บังคับ ที่อยู่ IP ที่ Google Analytics ใช้เพื่อรับข้อมูลทางภูมิศาสตร์สําหรับคําขอ

device

object ไม่บังคับ ตั้งค่าข้อมูลอุปกรณ์สำหรับคำขอในรูปแบบที่มีโครงสร้าง

validation_behavior

string

ไม่บังคับ ตั้งค่าลักษณะการตรวจสอบสำหรับคำขอ

RELAXED หรือ ENFORCE_RECOMMENDATIONS ค่าเริ่มต้นจะเป็น RELAXED หากไม่ได้ระบุไว้

events[]

array ต้องระบุ อาร์เรย์ของรายการ event รายการ คุณส่งเหตุการณ์ได้สูงสุด 25 รายการต่อคำขอ ดูข้อมูลอ้างอิงเหตุการณ์สําหรับเหตุการณ์ที่แนะนํา

events[].name

string ต้องระบุ ชื่อเหตุการณ์ ชื่อเหตุการณ์ต้องมีอักขระไม่เกิน 40 ตัว ดูเหตุการณ์ที่แนะนําได้ที่เหตุการณ์

events[].params

object ไม่บังคับ พารามิเตอร์สําหรับเหตุการณ์ คุณส่งพารามิเตอร์ได้สูงสุด 25 รายการต่อเหตุการณ์ ดูพารามิเตอร์ที่แนะนําสําหรับแต่ละเหตุการณ์ได้ที่เหตุการณ์ และพารามิเตอร์เหตุการณ์ทั่วไป

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

พารามิเตอร์เหตุการณ์ทั่วไป

Measurement Protocol มีพารามิเตอร์เหตุการณ์ทั่วไปดังต่อไปนี้

คีย์ ประเภท คำอธิบาย

session_id

number ตัวเลขบวกที่ระบุเซสชันของผู้ใช้ จำเป็นสำหรับกรณีการใช้งานทั่วไปหลายกรณี ต้องตรงกับนิพจน์ทั่วไป ^\d+$

ต้องดึงข้อมูลโดยใช้ Firebase SDK:

engagement_time_msec

number ระยะเวลาของการมีส่วนร่วมของผู้ใช้ในหน่วยมิลลิวินาทีสําหรับเหตุการณ์ ใช้ค่าที่แสดงระยะเวลาการมีส่วนร่วมของผู้ใช้นับตั้งแต่เหตุการณ์ก่อนหน้า

timestamp_micros

number เวลา Unix Epoch ในหน่วยไมโครวินาทีสำหรับเหตุการณ์ ใช้พารามิเตอร์นี้เพื่อลบล้างการประทับเวลาของเหตุการณ์

แอตทริบิวต์ consent จะกำหนดค่าประเภทและสถานะความยินยอม หากคุณไม่ระบุ consent, Google Analytics จะใช้การตั้งค่าความยินยอมจากการโต้ตอบออนไลน์ที่เกี่ยวข้องสําหรับไคลเอ็นต์หรืออินสแตนซ์แอป

คีย์ ประเภท คำอธิบาย

ad_user_data

string

ไม่บังคับ ความยินยอมในการส่งข้อมูลผู้ใช้จากเหตุการณ์และพร็อพเพอร์ตี้ผู้ใช้ของคำขอไปยัง Google เพื่อวัตถุประสงค์ในการโฆษณา

GRANTED หรือ DENIED

ad_personalization

string

ไม่บังคับ ความยินยอมสำหรับโฆษณาที่ปรับตามโปรไฟล์ของผู้ใช้

GRANTED หรือ DENIED

ข้อมูลทางภูมิศาสตร์

แอตทริบิวต์ user_location และ ip_override จะให้ข้อมูลทางภูมิศาสตร์ user_location จะมีความสำคัญเหนือ ip_override

โครงสร้างของช่อง user_location มีดังนี้ ระบุแอตทริบิวต์ให้มากที่สุดเท่าที่จะเป็นไปได้ เราขอแนะนำให้ใช้ country_id และ region_id เป็นอย่างน้อย

คีย์ ประเภท คำอธิบาย

city

string ไม่บังคับ ชื่อเมือง หากเมืองอยู่ในสหรัฐอเมริกา ให้ตั้งค่า country_id และ region_id ด้วยเพื่อให้ Google Analytics แมปชื่อเมืองกับรหัสเมืองได้อย่างถูกต้อง

region_id

string ไม่บังคับ ประเทศและพื้นที่ย่อยตามมาตรฐาน ISO 3166 เช่น US-CA, US-AR, CA-BC, GB-LND, CN-HK

country_id

string ไม่บังคับ ประเทศในรูปแบบ ISO 3166-1 alpha-2 เช่น US, AU, ES, FR

subcontinent_id

string ไม่บังคับ อนุทวีปในรูปแบบ UN M49 เช่น 011, 021, 030, 039

continent_id

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 เป็นอย่างน้อย

คีย์ ประเภท คำอธิบาย

category

string ไม่บังคับ หมวดหมู่ของอุปกรณ์ เช่น desktop tablet mobile smart TV

language

string ไม่บังคับ ภาษาในรูปแบบ ISO 639-1 เช่น en, en-US

screen_resolution

string ไม่บังคับ ความละเอียดของอุปกรณ์ในรูปแบบ WIDTHxHEIGHT เช่น 1280x2856, 1080x2340

operating_system

string ไม่บังคับ ระบบปฏิบัติการหรือแพลตฟอร์ม เช่น MacOS

operating_system_version

string ไม่บังคับ เวอร์ชันของระบบปฏิบัติการหรือแพลตฟอร์ม เช่น 13.5

model

string ไม่บังคับ รุ่นของอุปกรณ์ เช่น Pixel 9 Pro, Samsung Galaxy S24

brand

string ไม่บังคับ แบรนด์ของอุปกรณ์ เช่น Google, Samsung

browser

string ไม่บังคับ แบรนด์หรือประเภทของเบราว์เซอร์ เช่น Chrome, Firefox

browser_version

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_activeview
  • ad_click
  • ad_exposure
  • ad_query
  • ad_reward
  • adunit_exposure
  • app_clear_data
  • app_exception
  • app_install
  • app_remove
  • app_store_refund
  • app_update
  • app_upgrade
  • dynamic_link_app_open
  • dynamic_link_app_update
  • dynamic_link_first_open
  • error
  • firebase_campaign
  • firebase_in_app_message_action
  • firebase_in_app_message_dismiss
  • firebase_in_app_message_impression
  • first_open
  • first_visit
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

นอกจากนี้ เหตุการณ์ ad_impression, in_app_purchase และ screen_view ยังอนุญาตให้ใช้กับสตรีมแอปเท่านั้น

ชื่อพารามิเตอร์ที่สงวนไว้

ชื่อพารามิเตอร์ต่อไปนี้เป็นชื่อที่สงวนไว้และไม่สามารถใช้ได้

  • firebase_conversion

ชื่อพารามิเตอร์ต้องไม่ขึ้นต้นด้วยรายการต่อไปนี้

  • _ (underscore)
  • firebase_
  • ga_
  • google_
  • gtag.

ชื่อพร็อพเพอร์ตี้ผู้ใช้ที่สงวนไว้

ชื่อพร็อพเพอร์ตี้ผู้ใช้ต่อไปนี้เป็นชื่อที่สงวนไว้และไม่สามารถใช้ได้

  • first_open_time
  • first_visit_time
  • last_deep_link_referrer
  • user_id
  • first_open_after_install

นอกจากนี้ ชื่อพร็อพเพอร์ตี้ผู้ใช้ต้องไม่ขึ้นต้นด้วย

  • _ (underscore)
  • firebase_
  • ga_
  • google_