本文說明如何使用 Measurement Protocol 將資料傳送至 Google Analytics (分析)。
總覽
使用 Measurement Protocol 將資料傳送至 Google Analytics (分析) 的程序分為 2 個部分:
- 傳輸資料 (目的地和方式)
- 酬載 – 您傳送的資料
本文件說明如何設定這兩種格式。
運輸
網址端點
您可以使用 Measurement Protocol 傳送資料,方法是向以下端點發出 HTTP 要求:
https://www.google-analytics.com/collect
所有資料都應該使用 HTTPS 通訊協定安全傳送。
您可以使用 POST 或 GET 要求來傳送資料。
使用 POST
建議您透過 POST 傳送資料,因為這樣可以取得更大的酬載。使用 POST 時,請發出下列 HTTP 要求:
User-Agent: user_agent_string POST https://www.google-analytics.com/collect payload_data
在此情況下:
- user_agent_string:是
格式化的使用者代理程式字串,分別用於計算以下維度:瀏覽器、平台和行動裝置功能。
如未設定這個值,系統就不會計算上方資料。
- payload_data - 張貼要求的
BODY
。內文必須包含 1 個 URI 編碼酬載,且不得超過 8192 個位元組。 - IP 位址:在 HTTP 要求中隱含傳送,可用來計算 Google Analytics (分析) 中的所有地理區域 / 網路維度。
GET
對於無法傳送 POST 資料的環境,您也可以將 HTTP GET 要求傳送至同一個端點:
GET /collect?payload_data HTTP/1.1 Host: https://www.google-analytics.com User-Agent: user_agent_string
酬載資料會以 URI 逸出查詢參數的形式傳送。整個已編碼的網址長度不得超過 8000 個位元組。
快取清除
在某些環境 (例如瀏覽器) 中,HTTP GET 要求可能會快取。系統快取要求後,系統可能會從快取中擷取後續要求,而不會傳送至 Google Analytics (分析)。為了清除快取,Measurement Protocol 提供了可隨機設定的特殊參數 (z
)。這麼做可確保所有 Measurement Protocol 要求都不重複,不會從快取中擷取後續要求。
使用快取破壞時,強烈建議您將這個參數新增為酬載中的 last 參數。
https://www.google-analytics.com/collect?payload_data&z=123456
回應代碼
如果收到 HTTP 要求,Measurement Protocol 會傳回 2xx
狀態碼。如果酬載資料格式錯誤、酬載資料不正確或未由 Google Analytics (分析) 處理,Measurement Protocol 不會傳回錯誤代碼。
如未取得 2xx
狀態碼,請「不要」重試要求。而是應該停止並修正 HTTP 要求中的所有錯誤。
酬載資料
Google Analytics (分析) 使用 Measurement Protocol 收集的所有資料都會以酬載的形式傳送。酬載與網址查詢字串類似,其中每個參數都有一個鍵和值,並以 =
字元分隔,每個組合則以 &
字元分隔。例如:
key1=val1&key2=val2
每個酬載都具有可控管的規則:必要值、URI 編碼、可一起傳送的參數以及參數長度。此外,每個參數都有需要特定格式的類型。以下各節將說明這些規則。
請參閱參數參考資料,當中詳列可使用 Measurement Protocol 傳送的所有參數。
所有命中的必要值
每個酬載都必須包含下列參數:
名稱 | 參數 | 範例 | 說明 |
---|---|---|---|
通訊協定版本 | v |
v=1 |
通訊協定版本。值應為 1 。 |
追蹤 ID | tid |
tid=UA-123456-1 |
用來區分要傳送資料的 Google Analytics (分析) 資源。 |
用戶端 ID | cid |
cid=xxxxx |
特定使用者的專屬 ID。 |
命中類型 | t |
t=pageview |
針對特定使用者收集的互動類型。 |
Client ID
和 Hit Type
資料是直接對應至 Google Analytics (分析) 資料模型的值。如要追蹤前往 /pageA
、/pageB
和 /pageC
的使用者 5555
,請傳送下列 3 個酬載:
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
請注意,/
已編碼為 %2F
。
網址編碼值
所有傳送至 Google Analytics (分析) 的值都必須為 UTF-8 和網址編碼。
如要傳送含有 /my page €
值的金鑰 dp
,您必須先確認這是 UTF-8 編碼,然後進行網址編碼,進而產生最終字串:
dp=%2Fmy%20page%20%E2%82%AC
如果任何字元編碼錯誤,這些字元會替換為萬國碼替換字元 xFFFD
。
特定命中類型的必要值
部分參數可能會隨特定命中類型傳送。舉例來說,pageview
命中類型必須一併設定網頁路徑參數 (dp
)。參數參考資料說明瞭各個命中類型需要哪些參數。
最大長度
Measurement Protocol 中的部分文字值具有特定長度上限 (以位元組為單位)。舉例來說,文件參照網址欄位 dr
的長度上限為 2,048 個位元組。如果任一值超過長度上限,系統就會自動截斷這些值。如果多位元組字元超過長度上限,整個字元都會遭到截斷。
支援的資料類型
Measurement Protocol 中的每個資料欄位都屬於特定類型,有各自的驗證規則。只要有任何參數值不符合驗證規則,Google Analytics (分析) 就會忽略該參數,不會由 Google Analytics (分析) 處理。 所有其他參數都會照常處理。
Measurement Protocol 支援下列資料類型:
請注意,個別資料欄位可能有各自的限制。如需所有資料欄位和可接受的類型的完整清單,請參閱欄位參考資料。
文字
用於表示字串。文字欄位會額外處理。系統會移除所有開頭和結尾的空白字元。在內部執行作業中,如有兩個以上的空白字元 (包括空格、定位點和換行字元等) 會縮短為單一空格字元,系統會在任何截斷發生前,先將這項轉換套用至原始文字。例如:
Hello World
會變成:
Hello World
幣別
用於表示貨幣總價值。小數點會用來做為貨幣整個與分數部分之間的分隔符號。精確度最多到小數點後 6 位。以下是貨幣欄位的有效值:
1000.000001
將值傳送至 Google Analytics (分析) 後,所有文字都會移除,直到第一個數字、-
字元或 .
(十進位) 字元為止。舉例來說:
$-55.00
會變成:
-55.00
布林值
用於判斷特定值是 True 還是 False。以下為有效值:
1
- 是0
- 否
整數
用來代表整數。這個值會以已登入的 int64 形式儲存
編號
用來代表整數或浮點數。