Tài liệu này mô tả cách gửi dữ liệu đến Google Analytics bằng Measurement Protocol.
Tổng quan
Có 2 phần để gửi dữ liệu đến Google Analytics bằng Measurement Protocol:
- Phương tiện vận chuyển – đến địa điểm và cách thức bạn gửi dữ liệu
- Trọng tải – dữ liệu bạn gửi
Tài liệu này mô tả cách định dạng cả hai định dạng này.
Phương tiện vận chuyển
Điểm cuối URL
Bạn gửi dữ liệu bằng Measurement Protocol bằng cách gửi các yêu cầu HTTP đến điểm cuối sau:
https://www.google-analytics.com/collect
Tất cả dữ liệu phải được gửi an toàn bằng giao thức HTTPS.
Bạn có thể gửi dữ liệu bằng cách sử dụng yêu cầu POST hoặc GET.
Sử dụng POST
Bạn nên gửi dữ liệu qua POST vì dữ liệu cho phép tải trọng lớn hơn. Khi sử dụng POST, hãy đưa ra yêu cầu HTTP sau:
User-Agent: user_agent_string POST https://www.google-analytics.com/collect payload_data
Trong trường hợp:
- user_agent_string – Là một
chuỗi tác nhân người dùng được định dạng dùng để tính toán các thứ nguyên sau: trình duyệt, nền tảng và khả năng của thiết bị di động.
Nếu bạn không đặt giá trị này, thì hệ thống sẽ không tính toán dữ liệu trên.
- payload_data –
BODYcủa yêu cầu đăng. Phần nội dung phải bao gồm chính xác 1 trọng tải được mã hoá URI và không được dài hơn 8192 byte. - Địa chỉ IP – Được gửi ngầm trong yêu cầu HTTP và dùng để tính toán tất cả các phương diện địa lý/mạng trong Google Analytics.
XEM
Trong các môi trường mà bạn không thể gửi dữ liệu POST, bạn cũng có thể gửi yêu cầu HTTP GET đến cùng một điểm cuối:
GET /collect?payload_data HTTP/1.1 Host: https://www.google-analytics.com User-Agent: user_agent_string
Trong trường hợp dữ liệu trọng tải được gửi dưới dạng tham số truy vấn thoát URI. Độ dài của toàn bộ URL được mã hoá không được vượt quá 8000 byte.
Chặn bộ nhớ đệm
Trong một số môi trường, chẳng hạn như trình duyệt, các yêu cầu HTTP GET có thể được lưu vào bộ nhớ đệm.
Khi một yêu cầu được lưu vào bộ nhớ đệm, các yêu cầu tiếp theo có thể được truy xuất từ bộ nhớ đệm và không được gửi đến Google Analytics. Để kích hoạt bộ nhớ đệm,
Measurement Protocol cung cấp một thông số đặc biệt
(z) có thể được đặt bằng một số ngẫu nhiên. Việc này đảm bảo rằng tất cả các yêu cầu của Measurement Protocol đều là duy nhất và các yêu cầu tiếp theo sẽ không được truy xuất từ bộ nhớ đệm.
Khi sử dụng trình chặn truy xuất bộ nhớ đệm, bạn nên thêm tham số này làm tham số cuối cùng trong tải trọng.
https://www.google-analytics.com/collect?payload_data&z=123456
Mã phản hồi
Measurement Protocol sẽ trả về mã trạng thái 2xx nếu nhận được yêu cầu HTTP. Measurement Protocol sẽ không trả về mã lỗi nếu
dữ liệu trọng tải 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ý.
Nếu không nhận được mã trạng thái 2xx, bạn KHÔNG nên thử yêu cầu lại. Thay vào đó, bạn nên dừng và sửa mọi lỗi trong yêu cầu HTTP.
Dữ liệu phần tải
Tất cả dữ liệu mà Google Analytics thu thập bằng Measurement Protocol sẽ được gửi dưới dạng một gói dữ liệu. Trọng tải giống với một chuỗi truy vấn URL, trong đó mỗi tham số có một khoá và giá trị, được phân tách bằng một ký tự = và mỗi cặp được phân tách bằng một ký tự &.
Ví dụ:
key1=val1&key2=val2
Mỗi trọng tải có các quy tắc chi phối: giá trị bắt buộc, mã hóa URI, tham số có thể gửi cùng nhau và độ dài tham số. Ngoài ra, mỗi tham số có một loại cụ thể yêu cầu định dạng cụ thể. Các phần sau đây sẽ hướng dẫn về những quy tắc này.
Hãy đọc Tài liệu tham khảo về thông số để xem danh sách đầy đủ tất cả các thông số mà bạn có thể gửi bằng Measurement Protocol.
Giá trị bắt buộc cho tất cả các lượt truy cập
Các thông số sau phải nằm trong mỗi trọng tải:
| Tên | Thông số | Ví dụ: | Nội dung mô tả |
|---|---|---|---|
| Phiên bản giao thức | v |
v=1 |
Phiên bản giao thức. Giá trị phải là 1. |
| Mã theo dõi | tid |
tid=UA-123456-1 |
Mã phân biệt với tài sản Google Analytics mà bạn muốn gửi dữ liệu. |
| Client ID | cid |
cid=xxxxx |
Mã nhận dạng duy nhất của một người dùng cụ thể. |
| Loại lần truy cập | t |
t=pageview |
Loại tương tác được thu thập cho một người dùng cụ thể. |
Dữ liệu Client ID và Hit Type
là các giá trị liên kết trực tiếp với mô hình dữ liệu Google Analytics.
Nếu muốn theo dõi người dùng 5555 đã truy cập vào
/pageA, /pageB và /pageC,
bạn sẽ gửi 3 trọng tải sau:
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageA v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageB v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageC
Xin lưu ý rằng / đã được mã hoá thành %2F.
Giá trị mã hóa URL
Tất cả các giá trị được gửi đến Google Analytics đều phải được mã hoá bằng phương thức UTF-8 và URL được mã hoá.
Để gửi khoá dp với giá trị /my page €, trước tiên bạn cần đảm bảo đây là mã hoá UTF-8, sau đó là mã hoá url, dẫn đến chuỗi cuối cùng:
dp=%2Fmy%20page%20%E2%82%AC
Nếu có bất kỳ ký tự nào được mã hoá không chính xác, thì các ký tự đó sẽ được thay thế bằng ký tự thay thế unicode xFFFD.
Giá trị bắt buộc cho một số loại truy cập nhất định
Một số thông số chỉ có thể được gửi với các loại lượt truy cập cụ thể.
Ví dụ: loại lượt truy cập pageview yêu cầu cũng phải đặt thông số Đường dẫn trang (dp). Tài liệu tham khảo về thông số mô tả các thông số cần thiết cho những loại lượt truy cập.
Chiều dài tối đa
Một số giá trị văn bản trong Measurement Protocol có độ dài tối đa cụ thể tính bằng byte. Ví dụ: trường đường liên kết giới thiệu tài liệu dr có độ dài tối đa là 2.048 Byte. Những giá trị lớn hơn độ dài tối đa sẽ được tự động cắt bớt. Nếu một ký tự nhiều byte vượt quá độ dài tối đa, thì toàn bộ ký tự sẽ bị cắt ngắn.
Loại dữ liệu được hỗ trợ
Mỗi trường dữ liệu trong Measurement Protocol thuộc một loại cụ thể, mỗi loại có các quy tắc xác thực riêng. Nếu bất kỳ giá trị thông số nào không tuân thủ quy tắc xác thực, thì thông số cụ thể đó sẽ bị Google Analytics bỏ qua và không được xử lý. Mọi thông số khác sẽ được xử lý như bình thường.
Measurement Protocol hỗ trợ các loại dữ liệu sau:
Xin lưu ý rằng từng trường dữ liệu có thể có các quy định hạn chế riêng. Hãy xem Tài liệu tham khảo về trường để biết danh sách đầy đủ tất cả các trường dữ liệu và loại được chấp nhận.
Văn bản
Dùng để biểu thị các chuỗi. Quá trình xử lý bổ sung được thực hiện trên các trường văn bản. Tất cả các ký tự khoảng trắng ở đầu và cuối đều bị xóa. Các nội dung chạy nội bộ gồm hai ký tự khoảng trắng trở lên (bao gồm dấu cách, thẻ, dòng mới, v.v.) được giảm xuống còn một ký tự dấu cách. Phép biến đổi này được áp dụng cho văn bản thô trước khi cắt bớt. Ví dụ:
Hello World
sẽ trở thành:
Hello World
Tiền tệ
Dùng để thể hiện tổng giá trị của một đơn vị tiền tệ. Dấu thập phân được sử dụng làm dấu phân tách giữa toàn bộ và phần thập phân của đơn vị tiền tệ. Độ chính xác lên tới 6 chữ số phần thập phân. Các trường sau đây hợp lệ cho trường đơn vị tiền tệ:
1000.000001
Sau khi giá trị được gửi đến Google Analytics, tất cả văn bản sẽ bị xoá cho đến khi chữ số đầu tiên, ký tự - hoặc ký tự . (thập phân). Do đó:
$-55.00
sẽ trở thành:
-55.00
Boolean
Dùng để xác định xem một giá trị có đúng hay sai. Các giá trị hợp lệ là:
1– Đúng0– Sai
Số nguyên
Dùng để biểu thị một số nguyên. Giá trị này được lưu trữ dưới dạng một int64 đã ký
Số
Dùng để biểu thị một số nguyên hoặc một số thực dấu phẩy động.