Hãy thử máy chủ MCP cho Google Analytics. Cài đặt từ GitHub và xem thông báo để biết thêm thông tin chi tiết.

Trang này được dịch bởi Cloud Translation API.

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:

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

Tham số truy vấn

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

Tên thông số	Mô tả
`api_secret`	Bắt buộc. Khoá bí mật API trong giao diện người dùng Google Analytics. Bạn có thể tìm thấy khoá bí mật trong mục Quản trị > Luồng dữ liệu > Chọn luồng của bạn > Measurement Protocol > Tạo. Riêng tư đối với tổ chức của bạn. Bạn nên thường xuyên cập nhật để tránh gửi quá nhiều thư rác.

`api_secret`

Bắt buộc. Khoá bí mật API trong giao diện người dùng Google Analytics.

Bạn có thể tìm thấy khoá bí mật trong mục Quản trị > Luồng dữ liệu > Chọn luồng của bạn > Measurement Protocol > Tạo.

Riêng tư đối với tổ chức của bạn. Bạn nên thường xuyên cập nhật để tránh gửi quá nhiều thư rác.

Nội dung POST JSON

Khoá	Loại	Mô tả
`user_id`	`string`	Không bắt buộc. Giá trị nhận dạng riêng biệt cho một người dùng. Hãy xem bài viết User-ID cho hoạt động 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. Chỉ được chứa các ký tự utf-8.
`timestamp_micros`	`number`	Không bắt buộc. Dấu thời gian Unix, micrô giây, không phải mili giây. Biểu thị thời gian diễn ra sự kiện. Chỉ nên đặt để ghi lại những sự kiện đã xảy ra trong quá khứ. Có thể được ghi đè bằng `user_property` hoặc dấu thời gian của sự kiện. Bạn có thể đặt ngày diễn ra sự kiện trước đó tối đa 3 ngày dương 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.
`user_data`	`object`	Không bắt buộc. Dữ liệu do người dùng cung cấp.
`consent`	`object`	Không bắt buộc. Chế độ cài đặt về 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 dùng nữa: Hãy sử dụng trường `ad_personalization` của `consent`. Không bắt buộc. Đặt thành `true` để cho biết dữ liệu của người dùng không được dùng cho quảng cáo được cá nhân hoá.
`user_location`	`object`	Không bắt buộc. Đặt thông tin địa lý cho yêu cầu ở định dạng có cấu trúc.
`ip_override`	`string`	Không bắt buộc. Địa chỉ IP mà Google Analytics sử dụng để lấy thông tin địa lý cho yêu cầu.
`device`	`object`	Không bắt buộc. Đặt thông tin thiết bị cho yêu cầu ở định dạng có cấu trúc.
`events[]`	`array`	Bắt buộc. Một mảng gồm `event` mục. Bạn có thể gửi tối đa 25 sự kiện cho 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 phần Sự kiện để biết tất cả các lựa chọn.
`events[].params`	`object`	Không bắt buộc. Thông số cho sự kiện. Hãy xem phần Sự kiện để biết các thông số được đề xuất cho từng sự kiện và Thông số sự kiện chung.

Thông số sự kiện chung

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

Khoá	Loại	Mô tả
`session_id`	`number`	Một số dương xác định phiên người dùng. Bắt buộc đối với một số trường hợp sử dụng phổ biến. Phải khớp với biểu thức chính quy `^\d+$`.
`engagement_time_msec`	`number`	Thời lượng tương tác của người dùng, tính bằng mili giây, cho sự kiện. Sử dụng một giá trị phản ánh khoảng thời gian tương tác của người dùng kể từ sự kiện trước đó.
`timestamp_micros`	`number`	Khoảng thời gian Unix, tính bằng micro giây, cho sự kiện. Sử dụng tham số này để ghi đè dấu thời gian của sự kiện.

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.

Khoá Loại Mô tả

Khoá	Loại	Mô tả
`ad_user_data`	`string`	Không bắt buộc. 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. `GRANTED` hoặc `DENIED`.
`ad_personalization`	`string`	Không bắt buộc. Sự đồng ý của người dùng đối với quảng cáo được cá nhân hoá. `GRANTED` hoặc `DENIED`.

`ad_user_data`

string

Không bắt buộc. 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.

GRANTED hoặc DENIED.

`ad_personalization`

string

Không bắt buộc. Sự đồng ý của người dùng đối với quảng cáo được cá nhân hoá.

GRANTED hoặc DENIED.

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.

Khoá	Loại	Mô tả
`city`	`string`	Không bắt buộc. Tên thành phố. Nếu thành phố đó ở Hoa Kỳ, hãy đặt cả `country_id` và `region_id` để Google Analytics có thể liên kết chính xác tên thành phố với mã nhận dạng thành phố.
`region_id`	`string`	Không bắt buộc. Quốc gia và tiểu bang theo tiêu chuẩn ISO 3166. Ví dụ: `US-CA`, `US-AR`, `CA-BC`, `GB-LND`, `CN-HK`.
`country_id`	`string`	Không bắt buộc. Quốc gia ở định dạng ISO 3166-1 alpha-2. Ví dụ: `US`, `AU`, `ES`, `FR`.
`subcontinent_id`	`string`	Không bắt buộc. Tiểu lục địa ở định dạng UN M49. Ví dụ: `011`, `021`, `030`, `039`.
`continent_id`	`string`	Không bắt buộc. Châu lục ở định dạng UN M49. Ví dụ: `002`, `019`, `142`, `150`.

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.

Khoá	Loại	Mô tả
`category`	`string`	Không bắt buộc. Danh mục của thiết bị. Ví dụ: `desktop`, `tablet`, `mobile`, `smart TV`.
`language`	`string`	Không bắt buộc. Ngôn ngữ ở định dạng ISO 639-1. Ví dụ: `en`, `en-US`.
`screen_resolution`	`string`	Không bắt buộc. Độ phân giải của thiết bị, có định dạng là `WIDTHxHEIGHT`. Ví dụ: `1280x2856`, `1080x2340`.
`operating_system`	`string`	Không bắt buộc. Hệ điều hành hoặc nền tảng. Ví dụ: `MacOS`.
`operating_system_version`	`string`	Không bắt buộc. Phiên bản của hệ điều hành hoặc nền tảng. Ví dụ: `13.5`.
`model`	`string`	Không bắt buộc. Mẫu thiết bị. Ví dụ: `Pixel 9 Pro`, `Samsung Galaxy S24`.
`brand`	`string`	Không bắt buộc. Thương hiệu của thiết bị. Ví dụ: `Google`, `Samsung`.
`browser`	`string`	Không bắt buộc. Thương hiệu hoặc loại trình duyệt. Ví dụ: `Chrome`, `Firefox`.
`browser_version`	`string`	Không bắt buộc. Phiên bản của trình duyệt. Ví dụ: `136.0.7103.60`, `5.0`.

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

Tài liệu tham khảo về Measurement Protocol Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Giao thông vận tải

Phần tải

Tham số truy vấn

api_secret

Nội dung POST JSON

user_id

timestamp_micros

user_properties

user_data

consent

non_personalized_ads

user_location

ip_override

device

events[]

events[].name

events[].params

Thông số sự kiện chung

session_id

engagement_time_msec

timestamp_micros

Sự đồng ý

ad_user_data

ad_personalization

Thông tin về địa lý

city

region_id

country_id

subcontinent_id

continent_id

Thông tin thiết bị

category

language

screen_resolution

operating_system

operating_system_version

model

brand

browser

browser_version

Thông số tùy chỉnh

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

Tên dành riêng

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

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

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

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

`api_secret`

`user_id`

`timestamp_micros`

`user_properties`

`user_data`

`consent`

`non_personalized_ads`

`user_location`

`ip_override`

`device`

`events[]`

`events[].name`

`events[].params`

`session_id`

`engagement_time_msec`

`timestamp_micros`

`ad_user_data`

`ad_personalization`

`city`

`region_id`

`country_id`

`subcontinent_id`

`continent_id`

`category`

`language`

`screen_resolution`

`operating_system`

`operating_system_version`

`model`

`brand`

`browser`

`browser_version`