Measurement Protocol 參考資料

本文將說明如何使用 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 IDHit 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 形式儲存

編號

用來代表整數或浮點數。