Hướng dẫn này giải thích cách bạn có thể gửi sự kiện luồng dữ liệu web và ứng dụng Measurement Protocol của Google Analytics đến một máy chủ Google Analytics, để bạn có thể xem các sự kiện Measurement Protocol trong báo cáo Google Analytics.
Giá trị nhận dạng và tham số bắt buộc đối với các yêu cầu Measurement Protocol phụ thuộc vào việc bạn đang gửi sự kiện đến Luồng dữ liệu web hay Luồng dữ liệu ứng dụng.
- Đối với Luồng dữ liệu web (thường được đo lường bằng gtag.js hoặc Trình quản lý thẻ của Google), bạn sử dụng
measurement_idtrong URL yêu cầu vàclient_idtrong phần nội dung JSON để xác định phiên bản người dùng.client_idphải khớp với mã nhận dạng do thẻ Google Analytics tạo trên trang web của bạn. - Đối với Luồng dữ liệu ứng dụng (được đo lường bằng Firebase SDK), bạn sử dụng
firebase_app_idtrong URL yêu cầu vàapp_instance_idtrong phần nội dung JSON do SDK Google Analytics cho Firebase cung cấp.
Hướng dẫn này cung cấp ví dụ cho cả hai trường hợp.
Các thành phần chính của yêu cầu theo loại luồng
| Thành phần | Luồng dữ liệu web (gtag.js/GTM) | Luồng ứng dụng (Firebase) |
|---|---|---|
| Tham số URL của luồng phát trực tiếp | measurement_id |
firebase_app_id |
| Tham số URL khoá bí mật API | Bắt buộc | Bắt buộc |
| Trường nội dung JSON của mã thiết bị | client_id |
app_instance_id |
Chọn nền tảng bạn muốn xem trong hướng dẫn này:
Thẻ này hướng dẫn cách gửi các sự kiện từ máy chủ của bạn có tương quan với hoạt động của người dùng trong một Luồng dữ liệu ứng dụng bằng SDK Google Analytics cho Firebase. Xin lưu ý rằng những yêu cầu này sử dụng firebase_app_id và app_instance_id.
Điều kiện tiên quyết
Để gửi sự kiện bằng Measurement Protocol, bạn cần có mã nhận dạng cụ thể từ tài sản Google Analytics hoặc dự án Firebase.
Mã thông báo bí mật cho API
api_secret được dùng để xác thực các yêu cầu của bạn. Bạn cần giữ bí mật này một cách bí mật.
Cách tạo khoá bí mật mới:
- Chuyển đến Google Analytics rồi chuyển đến tài khoản và tài sản của bạn.
- Nhấp vào Quản trị ở dưới cùng bên trái.
- Trong mục Thu thập và sửa đổi dữ liệu, hãy nhấp vào Luồng dữ liệu.
- Chọn luồng dữ liệu Web hoặc Ứng dụng.
- Nhấp vào Mã thông báo bí mật cho API Measurement Protocol.
- Nhấp vào Tạo.
- Nhập biệt hiệu cho mã thông báo bí mật rồi nhấp vào Tạo.
Sao chép Giá trị khoá bí mật.
Mã ứng dụng Firebase
firebase_app_id xác định ứng dụng Firebase của bạn. Mã này không giống với app_instance_id.
Cách tìm mã ứng dụng Firebase:
- Mở dự án của bạn trong bảng điều khiển của Firebase.
- Nhấp vào biểu tượng bánh răng cài đặt bên cạnh Tổng quan về dự án rồi chọn Cài đặt dự án.
- Trong thẻ Chung, hãy chuyển đến phần Ứng dụng của bạn.
- Chọn ứng dụng iOS hoặc Android cụ thể.
- Sao chép giá trị Mã ứng dụng.
Định dạng yêu cầu
Nền tảng 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?firebase_app_id=<var>FIREBASE_APP_ID</var>&api_secret=<var>API_SECRET</var> 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 các tham số truy vấn URL yêu cầu (xem phần Điều kiện tiên quyết để biết thông tin chi tiết về cách tìm hoặc tạo các giá trị này):
api_secret: Mã thông báo bí mật cho API để xác thực yêu cầu.firebase_app_id: Mã ứng dụng Firebase của ứng dụng.
Bạn phải cung cấp một nội dung yêu cầu ở định dạng nội dung POST JSON 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
}
}
]
}
Bạn phải cung cấp app_instance_id trong nội dung yêu cầu để xác định một lượt cài đặt duy nhất của ứng dụng di động. Xin lưu ý rằng mã này khác với firebase_app_id dùng để xác định chính ứng dụng. Để biết thêm thông tin về app_instance_id và cách truy xuất mã này bằng Firebase SDK, hãy xem tài liệu tham khảo về app_instance_id.
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 một phiên mới mà không cần gửi session_start. Tìm hiểu cách tính số phiên.
Dùng thử
Dưới đây là ví dụ 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 sự kiện tutorial_begin và 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 phần Mã ứng dụng trong mục 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 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 Measurement Protocol nhận được yêu cầu.
Ví dụ sau đây gửi một 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ẽ chỉ định 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 sẽ 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ẽ chỉ định 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 sự kiện và thuộc tính người dùng trong khoảng thời gian tối đa là 72 giờ. 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
validation_behaviorkhông được đặt hoặc đượ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 ghi đè dấu thời gian của sự kiện hoặc thuộc tính đó thành 72 giờ trước. - Nếu
validation_behaviorđược đặt thànhENFORCE_RECOMMENDATIONS, thì Measurement Protocol sẽ từ chối sự kiện hoặc thuộc tính người dùng.
Google Analytics phải nhận được những sự kiện được gửi bằng Measurement Protocol nhằm mục đích liên kết 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 trong vòng 48 giờ kể từ dấu thời gian sự kiện phía máy khách ban đầu. Những sự kiện nhận được sau thời điểm này có thể không được xử lý như mong đợi, đặc biệt là cho các mục đích như phân bổ lượt chuyển đổi.
Các điểm hạn chế
Các giới hạn sau đây áp dụng cho việc gửi sự kiện Measurement Protocol đến Google Analytics:
- Các 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 thông số
session_idvàsession_numberkhi các giá trị của chúng được cung cấp bởi Mã phiên Analytics và Số phiên Analytics tương ứng là các biến tích hợp trong Trình quản lý thẻ của Google.Thông số mặt hàng 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 của ứng dụng được gửi đến Google Analytics sẽ không điền sẵn đối tượng Tìm kiếm trong Google Ads cho người dùng ứng dụng.
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. Hãy xem phần Tên dành riêng để biết thông tin chi tiết.
Tên dành riêng
Measurement Protocol có một số tên dành riêng mà bạn không thể dùng cho sự kiện, thông số hoặc thuộc tính người dùng.
Sau đây là những tên sự kiện thường gây nhầm lẫn:
screen_view: Sự kiện này chỉ được phép dùng cho luồng ứng dụng. Đối với luồng phát trên web, hãy sử dụngpage_view.ad_impression: Sự kiện này chỉ được phép dùng cho luồng ứng dụng.in_app_purchase: Sự kiện này chỉ được phép dùng cho luồng ứng dụng. Đối với luồng dữ liệu web, hãy sử dụng sự kiệnpurchase.
Để 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.