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

Tổng quan

Có hai phần để gửi dữ liệu đến Google Analytics bằng Giao thức đo lường:

  1. Phương tiện truyền tải – địa điểm và cách thức bạn gửi dữ liệu
  2. Tải trọng – dữ liệu mà 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.

Phương tiện vận chuyển

Điểm cuối URL

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

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

Để gửi một sự kiện, hãy gửi 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

Measurement Protocol 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 tải trọng không đúng định dạng, hoặc nếu dữ liệu trong tải trọng 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 2 phần:

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

tham số truy vấn

Tên thông số Nội dung mô tả

api_secret

Bắt buộc. 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 giao diện người dùng của Google Analytics để:
Quản trị > Luồng dữ liệu > chọn luồng dữ liệu > Measurement Protocol > Tạo

Bạn nên giữ bí mật những thông tin này cho tổ chức của mình. Nếu triển khai phía máy khách của Measurement Protocol, bạn nên thường xuyên xoay vòng các api_secret để tránh quá nhiều THƯ RÁC.

firebase_app_id

Bắt buộc. Mã ứng dụng Firebase. Giá trị nhận dạng cho ứng dụng Firebase. Bạn có thể tìm thấy giá trị nhận dạng cho ứng dụng Firebase. Có trong bảng điều khiển của Firebase bên dưới:
Project Settings > General > Your Apps > Mã ứng dụng

measurement_id

Mã đo lường. Giá trị nhận dạng cho Luồng dữ liệu. Có trong giao diện người dùng Google Analytics, trong mục:
Quản trị > Luồng dữ liệu > chọn luồng của bạn > Mã đo lường

Nội dung bài đăng ở định dạng JSON

Khoá Loại Nội dung mô tả

app_instance_id

string

Bắt buộc. Xác định duy nhất một lượt cài đặt cụ thể của một ứng dụng Firebase. Bạn cần truy xuất giá trị này thông qua SDK Firebase.

client_id

string

Bắt buộc. Xác định duy nhất một phiên bản người dùng của ứng dụng web. Hãy xem bài viết gửi sự kiện đến Measurement Protocol.

user_id

string

Không bắt buộc. Giá trị nhận dạng duy nhất của một người dùng. Hãy xem bài viết User-ID cho bản 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 thiết lập thuộc tính này để ghi lại các sự kiện đã xảy ra trong quá khứ. Bạn có thể ghi đè giá trị này qua user_property hoặc dấu thời gian của sự kiện. Sự kiện có thể được lùi ngày tối đa 3 ngày theo lịch dựa trên múi giờ của tài sản.

user_properties

object Không bắt buộc. Các thuộc tính người dùng cho hoạt động đo lường. Hãy xem bài viết Thuộc tính người dùng để biết thêm thông tin.
object Không bắt buộc. Đặt chế độ cài đặt lấy sự đồng ý cho yêu cầu. Hãy xem phần về sự đồ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 rằng bạn không nên 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 các mục sự kiện. Bạn có thể gửi tối đa 25 sự kiện trong mỗi yêu cầu. Hãy xem tài liệu tham khảo về sự kiện để biết tất cả cá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. 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 các 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 lấy sự đồng ý từ các lượt tương tác trực tuyến tương ứng cho phiên bản ứng dụng hoặc ứng dụng.

Khoá Loại Nội dung 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ố quy định, bạn có thể đưa 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 trong tải trọng Measurement Protocol.

  • Bạn có thể đưa thông số tuỳ chỉnh trong phạm vi người dùng 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 từng sự kiện.

Một số sự kiện có thông số đề xuất. Xem 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_impression
  • 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
  • screen_view
  • 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_