Tham chiếu Measurement Protocol

Tổng quan

Có hai phần để gửi dữ liệu đến Google Analytics bằng Measurement Protocol:

  1. Phương thức truyền tải – nơi và cách bạn gửi dữ liệu
  2. Gói dữ liệu – dữ liệu bạn gửi

Tài liệu này mô tả cách định dạng phương thức truyền tải và tải trọng.

Giao thông vận tải

Điểm cuối URL

Bạn gửi dữ liệu bằng Measurement Protocol bằng cách gửi yêu cầu POST HTTP đến điểm cuối sau:

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

Để gửi một sự kiện, hãy đưa ra yêu cầu POST sau:

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

Mã phản hồi

Giao thức đo lường luôn 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 dữ liệu trọng tải có định dạng không chính xác hoặc nếu dữ liệu trong trọng tải không chính xác hoặc không được Google Analytics xử lý.

Dung lượng

Dữ liệu được gửi đến Google Analytics bằng Dữ liệu Measurement Protocol trong hai phần:

  1. Tham số truy vấn
  2. Phần thân JSON POST

tham số truy vấn

Tên thông số Mô tả

api_secret

Bắt buộc. Một API Secret được tạo thông qua giao diện người dùng Google Analytics.

Để tạo khoá bí mật mới, hãy chuyển đến:
Quản trị > Luồng dữ liệu > chọn luồng của bạn > Measurement Protocol > Tạo trong giao diện người dùng Google Analytics

Bạn nên đặt những thông tin này ở chế độ riêng tư cho tổ chức của mình. Nếu triển khai giao thức đo lường phía máy khách, bạn nên thường xuyên xoay vòng các api_secret để tránh thư rác quá nhiều.

Nội dung của bài đăng JSON

Khoá Loại Mô tả

user_id

 string

Không bắt buộc. Giá trị nhận dạng duy nhất của người dùng. Hãy xem bài viết User-ID để phân tích trên nhiều nền tảng để biết thêm thông tin về giá trị nhận dạng này.

timestamp_micros

 number

Không bắt buộc. Dấu thời gian Unix (tính bằng micrô giây) cho thời gian liên kết với sự kiện. Bạn chỉ nên đặt tuỳ chọn này để ghi lại những sự kiện đã xảy ra trong quá khứ. Bạn có thể ghi đè giá trị này thông qua user_property hoặc dấu thời gian sự kiện. Bạn có thể đặt ngày cũ cho sự kiện trong tối đa 3 ngày theo lịch dựa trên múi giờ của cơ sở lưu trú.

user_properties

 object Không bắt buộc. Thuộc tính người dùng cho hoạt động đo lường. Hãy xem phần Thuộc tính người dùng để biết thêm thông tin.

user_data

 object Không bắt buộc. Dữ liệu do người dùng cung cấp. Hãy xem hướng dẫn về dữ liệu do người dùng cung cấp để biết thêm thông tin.
object Không bắt buộc. Đặt chế độ cài đặt về sự đồng ý cho yêu cầu. Hãy xem mục đồng ý để biết thêm thông tin.

non_personalized_ads

 boolean Không bắt buộc. Đặt thành true để cho biết không được sử dụng dữ liệu của người dùng cho quảng cáo được cá nhân hoá.

events[]

 array Bắt buộc. Một mảng chứa các mục sự kiện. Bạn có thể gửi tối đa 25 sự kiện cho mỗi yêu cầu. Xem tài liệu tham khảo về sự kiện cho tất cả sự kiện hợp lệ.

events[].name

 string Bắt buộc. Tên của sự kiện. Hãy xem tài liệu tham khảo về sự kiện để biết tất cả các tuỳ chọn.

events[].params

 object Không bắt buộc. Các thông số cho sự kiện. Hãy xem sự kiện để biết các thông số được đề xuất cho từng sự kiện.

Thuộc tính consent định cấu hình loại và trạng thái đồng ý. Nếu bạn không chỉ định consent, thì 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.

Khoá Loại Mô tả

ad_user_data

 string

Không bắt buộc. Đặt trạng thái đồng ý đối với việc gửi dữ liệu người dùng từ các sự kiện và thuộc tính người dùng của yêu cầu đến Google cho mục đích quảng cáo.

Phải là GRANTED hoặc DENIED.

ad_personalization

 string

Không bắt buộc. Đặt trạng thái đồng ý cho quảng cáo được cá nhân hoá cho người dùng.

Phải là GRANTED hoặc DENIED.

Thông số tùy chỉnh

Ngoài các thông số được quy đị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 Measurement Protocol.

  • Thông số tuỳ chỉnh ở phạm vi người dùng có thể được đưa vào đối tượng user_properties của tải trọng.
  • Bạn có thể đưa Thông số tuỳ chỉnh ở phạm vi sự kiện vào đối tượng events[].params của tải trọng.
  • Bạn có thể đưa thông số tuỳ chỉnh ở phạm vi mặt hàng vào mảng items cho mỗi sự kiện.

Một số sự kiện có các thông số được đề xuất. Hãy xem phần sự kiện để 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

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

Ngoài ra, tên thông số không được bắt đầu bằng:

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