การอ้างอิง 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. เนื้อความ POST ของ JSON

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

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

api_secret

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

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

แอตทริบิวต์ 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 instead, 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_