Tài liệu tham khảo về Measurement Protocol

Trang này mô tả cơ chế truyền tải và các thông số dữ liệu cho Measurement Protocol.

Giao thông vận tải

Tất cả dữ liệu phải được gửi một cách an toàn bằng cách sử dụng các yêu cầu HTTPS POST.

Gửi yêu cầu đến điểm cuối sau:

https://www.google-analytics.com/mp/collect

Nếu bạn muốn dữ liệu của mình được thu thập ở Liên minh Châu Âu, hãy sử dụng điểm cuối sau đây thay thế:

https://region1.google-analytics.com/mp/collect

Sau đây là yêu cầu POST mẫu:

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
PAYLOAD_DATA

Thay thế PAYLOAD_DATA bằng Tải trọng của yêu cầu.

Measurement Protocol trả về mã trạng thái 2xx nếu nhận được yêu cầu HTTP. Measurement Protocol không trả về mã lỗi nếu tải trọng bị sai định dạng hoặc nếu dữ liệu không chính xác hoặc không được Google Analytics xử lý.

Phần tải

Phần dữ liệu thực tế có hai phần:

1. Tham số truy vấn.
2. Nội dung POST của JSON.

Tham số truy vấn

Nội dung POST JSON

Thông số sự kiện chung

Measurement Protocol có các thông số sự kiện chung sau đây:

Sự đồng ý

Thuộc tính consent định cấu hình các loại và trạng thái consent. Nếu bạn không chỉ định consent, Google Analytics sẽ sử dụng chế độ cài đặt về sự đồng ý từ các lượt tương tác trực tuyến tương ứng cho ứng dụng khách hoặc phiên bản ứng dụng.

Thông tin về địa lý

Các thuộc tính user_location và ip_override cung cấp thông tin địa lý. user_location được ưu tiên hơn ip_override.

Sau đây là cấu trúc của trường user_location. Hãy cung cấp càng nhiều thuộc tính càng tốt. Bạn nên sử dụng ít nhất country_id và region_id.

Sau đây là một ví dụ về user_location:

"user_location": {
  "city": "Mountain View",
  "region_id": "US-CA",
  "country_id": "US",
  "subcontinent_id": "021",
  "continent_id": "019"
}

ip_override là một lựa chọn thay thế cho user_location. Nếu bạn gửi ip_override, Google Analytics sẽ lấy thông tin địa lý từ địa chỉ IP. Nếu bạn gửi user_location, Google Analytics sẽ bỏ qua ip_override.

Nếu bạn không gửi user_location hoặc ip_override, Google Analytics sẽ lấy thông tin địa lý từ các sự kiện gắn thẻ bằng cách sử dụng client_id.

Google Analytics áp dụng chế độ cài đặt dữ liệu vị trí chi tiết của tài sản cho yêu cầu, bất kể thông tin địa lý được gửi.

Thông tin thiết bị

Để gửi thông tin thiết bị, hãy sử dụng trường device. Sau đây là cấu trúc của trường device. Cung cấp nhiều thuộc tính nhất có thể. Bạn nên đặt ít nhất là category.

Đoạn mã sau đây cho thấy ví dụ về chế độ cài đặt 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"
}

Bất kể bạn chỉ định Google Analytics đều áp dụng chế độ cài đặt dữ liệu chi tiết về thiết bị của tài sản cho yêu cầu.

Thông số tùy chỉnh

Bạn có thể thêm các thông số tuỳ chỉnh ở phạm vi người dùng, phạm vi sự kiện và phạm vi mặt hàng vào tải trọng của Measurement Protocol.

• Bạn có thể thêm tham số tuỳ chỉnh ở phạm vi người dùng vào user_properties.
• Bạn có thể thêm thông số tuỳ chỉnh ở phạm vi sự kiện vào events[].params.
• Bạn có thể thêm tham số tuỳ chỉnh ở phạm vi mặt hàng vào items.

Giá trị được đề xuất cho một số sự kiện

Một số sự kiện có thông số được đề xuất. Hãy xem events để biết các thông số được đề xuất cho tất cả sự kiện được hỗ trợ.

Tên dành riêng

Có một số tên sự kiện, thông số và thuộc tính người dùng đã được dành riêng và không thể sử dụng:

Tên sự kiện chuyên dụng

Những tên sự kiện sau đây đã được dành riêng và không thể sử dụng:

• 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

Tên dành riêng cho thông số

Những tên thông số sau đây đã được dành riêng và không thể sử dụng:

• firebase_conversion

Tên thông số không được bắt đầu bằng những ký tự sau:

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

Tên thuộc tính người dùng chuyên dụng

Những tên thuộc tính người dùng sau đây đã được dành riêng và không thể sử dụng:

• first_open_time
• first_visit_time
• last_deep_link_referrer
• user_id
• first_open_after_install

Ngoài ra, tên thuộc tính người dùng không được bắt đầu bằng:

• _ (underscore)
• firebase_
• ga_
• google_