GA4 Measurement Protocol API 完整教學

更新時間：2026年6月4日

本篇將介紹GA4中的重要功能之一：Measurement Protocol API。

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

什麼是Measurement Protocol API？

Measurement Protocol API（簡稱MP協定）是一套由GA4提供的 API，可透過HTTP Request將事件資料直接傳送至GA4伺服器。

藉由MP協定，開發人員可以：

• 串聯線上與線下行為資料
• 同時衡量客戶端（Client-side）與伺服器端（Server-side）互動
• 傳送離線轉換事件
• 從不支援自動追蹤功能的裝置傳送事件（例如資訊看板、智慧手錶、IoT 裝置等）

例如：

• 客服電話成交
• 門市消費紀錄
• CRM 會員資料
• ERP 訂單資訊

都可以透過MP協定回傳至GA4。

Measurement Protocol API 的組成

Measurement Protocol API 主要由兩個部分組成：

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

如下圖：

運送（查詢參數）

官方文件有時也稱為「查詢參數」，決定資料要傳送到哪裡，以及使用哪些驗證資訊。

範例：

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

其中：

酬載（訊息內文） 

酬載（Payload）也就是 HTTP POST Request 的內容。

真正要傳送到 GA4 的事件資料都放在這裡。

主要參數如下：

Measurement Protocol AP的限制

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

此外：

• 事件名稱只能包含英文字母、數字與底線
• 必須以英文字母開頭

Measurement Protocol與Measurement Protocol API的差異

許多人會發現官方文件有時寫Measurement Protocol ，有時則寫Measurement Protocol API ，其實兩者指的是不同版本。

目前Google已逐漸將GA4文件統一簡稱為Measurement Protocol ，因此後續看到Measurement Protocol，通常都是指GA4的 MP 協定。

Measurement Protocol API 實作範例

假設要傳送 tutorial_begin 事件。

GA4中創建Measurement Protocol API密鑰

Measurement Protocol API的設定的位置在資料串流位置。

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

就可以獲取密鑰值：

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

傳送tutorial_begin事件

如要傳送 tutorial_begin 事件，從前端和伺服器發送的程式是不一樣的。

<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>

傳送資料的位置：https://www.google-analytics.com/mp/collect?measurement_id=G-3FK847CLRT&api_secret=nOrc0q9_RiqPsqsjBxmj9A

Payload裡：

{
"client_id":"123.456"
"non_personalized_ads":false
"events":[
   {
      "name":"tutorial_begin"
   }
 ]
}

驗證事件是否正確

當 MP 協定收到請求時，即使資料有誤，通常仍會回傳： 2xx 成功狀態碼。如果酬載資料格式錯誤、酬載中的資料不正確或未由 Google Analytics (分析) 處理，Measurement Protocol 則不會傳回錯誤代碼。

GA4也提供了一個驗證工具：https://ga-dev-tools.appspot.com/ga4-event-builder/，接要傳送的資料填進入：

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

點擊VALIDATE EVENT去驗證：

可以看到Event is valid，表示驗證成功。

驗證資料是否進入GA4

那麼可以返回到GA4中的即時報表中，可以在事件計數裡看到事件 tutorial_begin，即表示資料已成功寫入 GA4。

常見問題FAQ

被劃分到Unassigned管道