Hướng dẫn này giải thích cách bạn có thể gửi Measurement Protocol của Google Analytics các sự kiện trong luồng dữ liệu web và ứng dụng đến một máy chủ Google Analytics để xem các sự kiện Measurement Protocol trong báo cáo Google Analytics.
Chọn nền tảng mà bạn muốn xem trong hướng dẫn này:
Định dạng yêu cầu
Measurement Protocol của Google Analytics chỉ hỗ trợ các yêu cầu HTTP POST.
Để gửi một sự kiện, hãy sử dụng định dạng sau:
POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
PAYLOAD_DATA
Bạn phải cung cấp những thông tin sau trong URL yêu cầu:
api_secret: MÃ THÔNG BÁO BÍ MẬT CHO API được tạo trong giao diện người dùng Google Analytics.Để tạo một mã thông báo bí mật mới, hãy chuyển đến mục Quản trị > Thu thập và sửa đổi dữ liệu > Luồng dữ liệu > chọn luồng của bạn > Mã thông báo bí mật của API Measurement Protocol > Tạo.
firebase_app_id: Mã ứng dụng Firebase có trong bảng điều khiển của Firebase ở mục Cài đặt dự án > Chung > Ứng dụng của bạn > Mã ứng dụng.firebase_app_idkhông giống vớiapp_instance_id.firebase_app_idxác định ứng dụng của bạn, trong khiapp_instance_idxác định một lần cài đặt duy nhất của ứng dụng.
Bạn phải cung cấp nội dung yêu cầu ở định dạng nội dung JSON POST cho Measurement Protocol. Ví dụ:
{
"app_instance_id": "APP_INSTANCE_ID",
"events": [
{
"name": "login",
"params": {
"method": "Google",
"session_id": "SESSION_ID",
"engagement_time_msec": 100
}
}
]
}
Mặc dù session_start là một tên sự kiện được dành riêng,
việc tạo session_id mới sẽ tạo ra phiên mới mà không cần gửi
session_start. Tìm hiểu cách tính số phiên hoạt động
được.
Dùng thử
Sau đây là một ví dụ mà bạn có thể dùng để gửi nhiều sự kiện cùng một lúc. Ví dụ này
gửi một sự kiện tutorial_begin và một sự kiện
join_group đến máy chủ Google Analytics của bạn, bao gồm thông tin địa lý bằng cách sử dụng trường user_location, và bao gồm thông tin thiết bị
bằng cách sử dụng trường device.
const firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";
fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
app_instance_id: "APP_INSTANCE_ID",
events: [
{
name: "tutorial_begin",
params: {
"session_id": "SESSION_ID",
"engagement_time_msec": 100
}
},
{
name: "join_group",
params: {
"group_id": "G_12345",
"session_id": "SESSION_ID",
"engagement_time_msec": 150
}
}
],
user_location: {
city: "Mountain View",
region_id: "US-CA",
country_id: "US",
subcontinent_id: "021",
continent_id: "019"
},
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"
}
})
});
Định dạng của firebase_app_id là dành riêng cho nền tảng. Xem Mã ứng dụng
trong Tệp và đối tượng cấu hình Firebase.
Ghi đè dấu thời gian
Measurement Protocol sử dụng dấu thời gian đầu tiên mà giao thức này tìm thấy trong danh sách sau đây cho mỗi sự kiện và thuộc tính người dùng trong yêu cầu:
timestamp_microscủa sự kiện hoặc thuộc tính người dùng.timestamp_microscủa yêu cầu.- Thời gian mà Measurement Protocol nhận được yêu cầu.
Ví dụ sau đây gửi dấu thời gian ở cấp yêu cầu áp dụng cho tất cả các
sự kiện và thuộc tính
người dùng trong
yêu cầu. Do đó, Measurement Protocol sẽ gán dấu thời gian requestUnixEpochTimeInMicros cho các sự kiện tutorial_begin và join_group cũng như thuộc tính người dùng customer_tier.
{
"timestamp_micros": requestUnixEpochTimeInMicros,
"events": [
{
"name": "tutorial_begin"
},
{
"name": "join_group",
"params": {
"group_id": "G_12345",
}
}
],
"user_properties": {
"customer_tier": {
"value": "PREMIUM"
}
}
}
Ví dụ sau đây gửi dấu thời gian ở cấp yêu cầu, dấu thời gian ở cấp sự kiện và dấu thời gian ở cấp thuộc tính người dùng. Do đó, Measurement Protocol sẽ gán các dấu thời gian sau:
tutorialBeginUnixEpochTimeInMicroscho sự kiệntutorial_begincustomerTierUnixEpochTimeInMicroscho thuộc tính người dùngcustomer_tierrequestUnixEpochTimeInMicroscho sự kiệnjoin_groupvà thuộc tính người dùngnewsletter_reader.
{
"timestamp_micros": requestUnixEpochTimeInMicros,
"events": [
{
"name": "tutorial_begin",
"timestamp_micros": tutorialBeginUnixEpochTimeInMicros
},
{
"name": "join_group",
"params": {
"group_id": "G_12345",
}
}
],
"user_properties": {
"customer_tier": {
"value": "PREMIUM",
"timestamp_micros": customerTierUnixEpochTimeInMicros
},
"newsletter_reader": {
"value": "true"
}
}
}
Hành vi xác thực đối với các sự kiện và thuộc tính người dùng trong quá khứ
Bạn có thể đặt ngày cho các sự kiện và thuộc tính người dùng tối đa là 72 giờ trước. Nếu giá trị timestamp_micros sớm hơn 72 giờ trước, thì Measurement Protocol sẽ chấp nhận hoặc từ chối sự kiện hoặc thuộc tính người dùng như sau:
- Nếu bạn không đặt
validation_behaviorhoặc đặt thànhRELAXED, thì Measurement Protocol sẽ chấp nhận sự kiện hoặc thuộc tính người dùng nhưng sẽ ghi đè dấu thời gian của sự kiện hoặc thuộc tính người dùng thành 72 giờ trước. - Nếu bạn đặt
validation_behaviorthànhENFORCE_RECOMMENDATIONS, thì Measurement Protocol sẽ từ chối sự kiện hoặc thuộc tính người dùng.
Các sự kiện được gửi bằng Measurement Protocol nhằm mục đích kết hợp hoặc xử lý cùng với các sự kiện do SDK Google Analytics cho Firebase hoặc gtag.js thu thập phải được Google Analytics nhận trong vòng 48 giờ kể từ dấu thời gian sự kiện ban đầu ở phía máy khách. Các sự kiện nhận được muộn hơn thời gian này có thể không được xử lý như mong đợi, đặc biệt là đối với các mục đích như phân bổ lượt chuyển đổi.
Các điểm hạn chế
Các điểm hạn chế sau đây áp dụng cho việc gửi sự kiện Measurement Protocol đến Google Analytics:
- Yêu cầu có thể có tối đa 25 sự kiện.
- Sự kiện có thể có tối đa 25 thông số.
- Sự kiện có thể có tối đa 25 thuộc tính người dùng.
- Tên thuộc tính người dùng chỉ được có tối đa 24 ký tự.
- Giá trị thuộc tính người dùng chỉ được có tối đa 36 ký tự.
- Tên sự kiện chỉ được có tối đa 40 ký tự, chỉ được chứa các ký tự chữ và số, dấu gạch dưới và phải bắt đầu bằng một ký tự chữ cái.
- Tên thông số (bao gồm cả thông số mục) chỉ được có tối đa 40 ký tự, chỉ được chứa ký tự chữ và số, dấu gạch dưới và phải bắt đầu bằng một ký tự chữ cái.
Giá trị tham số (kể cả giá trị tham số của mặt hàng) chỉ được có tối đa 100 ký tự đối với tài sản Google Analytics chuẩn và tối đa 500 ký tự đối với tài sản Google Analytics 360.
Giới hạn này không áp dụng cho các tham số
session_idvàsession_numberkhi các giá trị của chúng được cung cấp bởi các biến được tạo sẵn tương ứng là Mã phiên Analytics và Số phiên Analytics trong Trình quản lý thẻ của Google.Thông số mục có thể có tối đa 10 thông số tuỳ chỉnh.
Nội dung bài đăng phải nhỏ hơn 130 kB.
Các sự kiện Measurement Protocol trong ứng dụng được gửi đến Google Analytics không điền sẵn đối tượng Tìm kiếm trong Google Ads cho người dùng ứng dụng.
Để biết các yêu cầu bổ sung của từng trường hợp sử dụng, hãy xem các trường hợp sử dụng phổ biến.