การอ้างอิง 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 ด้วย Payload ของคำขอ

Measurement Protocol จะแสดงรหัสสถานะ 2xx หากได้รับHTTP คำขอ Measurement Protocol จะไม่แสดงรหัสข้อผิดพลาดหากเพย์โหลดใช้ไม่ได้ หรือหากข้อมูลไม่ถูกต้องหรือ Google Analytics ไม่ได้ประมวลผล

เพย์โหลด

เพย์โหลดมี 2 ส่วน ดังนี้

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

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

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

api_secret

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

ดูได้ที่ผู้ดูแลระบบ > สตรีมข้อมูล > เลือกสตรีม > Measurement Protocol > สร้าง

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

เนื้อความ JSON POST

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

user_id

 string

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

timestamp_micros

 number

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

user_properties

 object ไม่บังคับ พร็อพเพอร์ตี้ผู้ใช้สำหรับการวัด

user_data

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

non_personalized_ads

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

user_location

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

ip_override

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

device

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

events[]

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

events[].name

 string ต้องระบุ ชื่อกิจกรรม ดูตัวเลือกทั้งหมดได้ที่กิจกรรม

events[].params

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

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

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

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

session_id

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

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 จะดึงข้อมูลทางภูมิศาสตร์จากการติดแท็กเหตุการณ์โดยใช้ client_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"
}

ไม่ว่าคุณจะระบุ Google Analytics จะใช้การตั้งค่าข้อมูลอุปกรณ์แบบละเอียดของพร็อพเพอร์ตี้กับคำขอ

พารามิเตอร์ที่กำหนดเอง

คุณสามารถใส่พารามิเตอร์ระดับผู้ใช้ ระดับเหตุการณ์ และระดับสินค้าที่กําหนดเอง ไว้ในเพย์โหลด 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
  • in_app_purchase
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

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

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

  • 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_