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
Quy trình gửi dữ liệu đến Google Analytics bằng Measurement Protocol gồm 2 phần:
- Phương tiện truyền tải – địa điểm và cách thức bạn gửi dữ liệu
- Tải trọng dữ liệu – dữ liệu mà bạn gửi đi
Tài liệu này mô tả cách định dạng cả hai.
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 HTTP đến điểm cuối sau:
https://www.google-analytics.com/collect
Tất cả dữ liệu phải được gửi một cách 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ì phương thức này cho phép có tải trọng lớn hơn. Khi sử dụng POST, hãy gửi yêu cầu HTTP sau đây:
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 phương diện sau: trình duyệt, nền tảng và chức 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 –
BODY
của yêu cầu đăng. Phần thân phải bao gồm chính xác 1 tải trọng được mã hoá URI và không được dài quá 8192 byte. - Địa chỉ IP – Được ngầm gửi trong yêu cầu HTTP và được sử dụng để tính tất cả các phương diện địa lý / mạng trong Google Analytics.
GET
Đối với 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 các 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
Nơi dữ liệu tải trọng đượ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 dài quá 8000 Byte.
Chặn truy xuất 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. Để xoá bộ nhớ đệm, Measurement Protocol sẽ 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. Điều này đảm bảo rằng tất cả các yêu cầu trên Measurement Protocol 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 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ý.
Nếu không nhận được mã trạng thái 2xx
thì bạn nên
KHÔNG 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 tải trọng
Tất cả dữ liệu do Google Analytics thu thập bằng Measurement Protocol sẽ được gửi dưới dạng tải trọng. Tải trọng này giống như 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 tải trọng có các quy tắc chi phối: giá trị bắt buộc, phương thức mã hoá URI, các tham số có thể được gửi cùng nhau và độ dài thông số. Ngoài ra, mỗi tham số có một loại cụ thể yêu cầu một định dạng cụ thể. Các phần sau đây sẽ trình bày về những quy tắc này.
Hãy đọc Tài liệu tham khảo về tham số để biết 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
Mỗi tải trọng phải có các tham số sau đây:
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 tài sản Google Analytics nào cần gửi dữ liệu. |
Client ID | cid |
cid=xxxxx |
Mã nhận dạng dành riêng cho 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 của 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 tải trọng 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
Lưu ý rằng /
đã được mã hoá thành %2F
.
Giá trị mã hoá URL
Tất cả các giá trị gửi đến Google Analytics đều phải sử dụng cả UTF-8 và
URL được mã hóa.
Để gửi khoá dp
chứa giá trị /my page €
, trước tiên bạn cần đảm bảo rằng khoá này đã được mã hoá UTF-8, sau đó mới được mã hoá url, dẫn đến chuỗi cuối cùng:
dp=%2Fmy%20page%20%E2%82%AC
Nếu bất kỳ ký tự nào được mã hoá không chính xác, thì chúng sẽ được thay thế bằng ký tự thay thế unicode xFFFD
.
Giá trị bắt buộc đối với một số loại lượt truy cập nhất định
Một số thông số chỉ có thể được gửi cùng 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 bạn cũng phải đặt tham số Đường dẫn trang (dp
). Tham chiếu tham số mô tả các tham số cần thiết cho các 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 liên kết giới thiệu tài liệu dr
có độ dài tối đa là 2.048 Byte. Nếu bất kỳ giá trị nào lớn hơn độ dài tối đa thì chúng sẽ tự động bị 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 bớt.
Các 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ể, và mỗi trường 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ủ các quy tắc xác thực, thì Google Analytics sẽ bỏ qua và không xử lý thông số cụ thể đó. Tất cả các 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 phần Tham chiếu 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 diễn 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ả ký tự khoảng trắng ở đầu và ở cuối đều bị xoá. Các lần chạy nội bộ có hai ký tự khoảng trắng trở lên (bao gồm dấu cách, thẻ, dòng mới, v.v.) sẽ bị giảm xuống còn một ký tự dấu cách. Quy tắc chuyển đổi này được áp dụng cho văn bản thô trước khi bị cắt bớt. Ví dụ:
Hello World
sẽ trở thành:
Hello World
Đơn vị 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 dùng làm dấu phân cách giữa phần nguyên 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. Giá trị sau đây phù hợp với 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 chữ số đầu tiên, ký tự -
hoặc ký tự .
(thập phân). Vì vậy:
$-55.00
sẽ trở thành:
-55.00
Boolean
Dùng để xác định xem một giá trị là true hay false. 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 int64 đã ký
Số
Dùng để biểu diễn một số nguyên hoặc số thực.