Tham chiếu Measurement Protocol

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 – Đúng
  • 0 – 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.