本文將說明如何使用 Measurement Protocol 將資料傳送至 Google Analytics (分析)。
總覽
使用 Measurement Protocol 將資料傳送至 Google Analytics (分析) 的程序分為兩個部分:
- 傳輸方式 – 您傳送資料的位置和方式
- 酬載 – 您傳送的資料
本文件將說明如何設定這兩種格式。
運輸
網址端點
您可以使用 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。 |
Client-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
如果任何字元編碼方式不正確,就會替換為 Unicode 替換字元 xFFFD
。
特定命中類型的必填欄位
部分參數只能與特定命中類型一起傳送。舉例來說,如要使用 pageview
命中類型,您還必須設定網頁路徑參數 (dp
)。參數參考資料說明瞭各種命中類型所需的參數。
最大長度
Measurement Protocol 中的部分文字值有特定的長度上限 (以位元組為單位)。舉例來說,文件參照網址欄位 dr
的長度上限為 2,048 位元組。任一值的長度大於長度上限,就會自動截斷。如果多位元組字元超過長度上限,系統會截斷整個字元。
支援的資料類型
Measurement Protocol 中的每個資料欄位都屬於特定類型,而每個欄位都有專屬的驗證規則。如果有任何參數值不符合驗證規則,Google Analytics (分析) 會忽略該參數,而不會處理。所有其他參數都會照常處理。
Measurement Protocol 支援下列資料類型:
請注意,個別資料欄位可能有各自的限制。如需所有資料欄位和可接受的類型的完整清單,請參閱欄位參考資料。
文字
用於表示字串。對文字欄位進行額外處理。移除所有開頭和結尾的空白字元。內部執行包含兩個以上的空白字元 (包括空格、定位點、換行字元等) 會縮減為單一空格字元。系統會先針對原始文字套用這項轉換,再進行截斷。例如:
Hello World
會變成:
Hello World
幣別
用來表示貨幣的總價值。小數點可用來做為貨幣整數和分數部分之間的分隔符號。精確度最多可以到小數點後 6 位。下列資訊適用於貨幣欄位:
1000.000001
將值傳送至 Google Analytics (分析) 後,所有文字都會遭到移除,直到第一個數字、-
字元或 .
(小數) 字元為止。舉例來說:
$-55.00
會變成:
-55.00
布林值
用於判斷值是 true 或 false。以下為有效值:
1
- 正確0
- 否
整數
用來代表整數。值會以已簽署的 int64 形式儲存
編號
用來代表整數或浮點數。