GA4 Measurement Protocol API 完整教學

更新時間：2026年8月4日

本篇將深入介紹GA4的重要功能——Measurement Protocol API。

透過此協定，您可將離線資料、CRM資料或伺服器端事件直接傳送至GA4，突破瀏覽器與App SDK的限制，實現更完整的數據蒐集與分析。

什麼是Measurement Protocol API？

Measurement Protocol API（簡稱MP協定）是一套由GA4提供的API，允許開發者透過HTTP Request將事件資料發送至GA4伺服器。

主要應用情境：

• 整合線上與線下行為數據（如門市消費、客服電話成交）
• 發送離線轉換事件（例如實體店鋪交易）
• 從無法自動追蹤的裝置（如資訊看板、智慧手錶、IoT設備）傳送事件

典型可上報的資料來源：客服通話記錄、門市POS交易、CRM會員屬性、ERP訂單狀態等。

Measurement Protocol與Measurement Protocol API的差異

官方文件曾混用兩種名稱，實則對應不同版本：

目前Google已逐步統一簡稱為Measurement Protocol，文件中若未特別標示，通常即指GA4版本。

Measurement Protocol API 的組成

MP協定主要由兩部分構成：

• 運送（Transport）
• 酬載（Payload）

如下圖：

運送（Transport）—— 查詢參數

決定資料送達的目標端點及驗證資訊。

範例：

https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}

必要查詢參數：

酬載（Payload）—— 訊息內文

即 HTTP POST Request 的 JSON Body，內含真正要傳送的事件資料。

主要欄位如下：

Measurement Protocol AP的限制

使用 Measurement Protocol API 時需注意以下限制：

實作範例：傳送tutorial_begin事件

步驟 1：取得API密鑰與評估ID

在GA4中点击「管理」——「資源設定」——「資料收集和修改」——「資料串流」—— 點擊你的網頁串流 ——「Measurement Protocol API 密鑰」——「建立」，暱稱命名為“CRM”。

完成後即可獲得：

• 評估ID：G-3FK847CLRT  （在GA4使用者介面中找到： 管理 > 資料串流 | 選擇串流 > 評估 ID）

步驟 2：發送請求

在伺服器端發送如下資訊：

<span style="font-size: 10pt;">const measurement_id = `G-3FK847CLRT`;
const api_secret = `nOrc0q9_RiqPsqsjBxmj9A`;

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: '123.456',
    events: [{
      name: 'tutorial_begin',
      params: {},
    }]
  })
});
</span>

幾點注意：

• client_id 必須為字串，若以數值傳送可能會被截斷精度（例如 123.456789 變成 123.4567）。
• 若您需要補報歷史事件，可在 Payload 中加入 timestamp_micros（微秒級 Unix 時間戳），但僅限過去72小時內的資料。
• 如欲保留流量歸因，建議同時傳送ga_session_id參數（可從瀏覽器 Cookie _ga_<container-id> 中取得）。

步驟 3：驗證事件是否正確

Measurement Protocol 在收到請求時，即使資料有誤，通常仍會回傳 HTTP 2xx 成功狀態，不會明確回報錯誤碼。

因此建議先使用官方驗證工具GA4 Event Builder，驗證事件結構是否正確。

將你的請求資訊填入

然後就可以在下面看到RequestInfo（運送）和Payload（酬載）：

確認 Payload 與步驟 2 的格式完全一致，再點擊VALIDATE EVENT去驗證：

若顯示「Event is valid」則表示格式正確。

步驟 4：驗證資料是否進GA4

驗證無誤後，可至GA4的即時報表查看該事件tutorial_begin是否出現於事件計數中。若出現，即代表資料成功寫入。

常見問題FAQ

透過MP發送的資料都被歸類為「Unassigned」管道，或工作階段來源顯示 (not set)？

有些人可能留意到，通過Measurement Protocol發送的資料都被劃分到Unassigned管道，如：

建議解決方式：若需保留歸因，請務必在事件參數中帶入ga_session_id欄位。