【GA4設定】用Measurement Protocol API實現離線資料傳送

文章目錄

什麼是Measurement Protocol API？

Measurement Protocol API簡稱MP協議，它可以透過 HTTP 要求將離線資料直接傳送至GA4伺服器，藉此提升網站串流和應用程式串流的成效，通過Measurement Protocol API，開發人員可以：

連結線上和離線行為
一併評估用戶端和伺服器端的互動
傳送非標準使用者互動的事件 (例如離線轉換)
從不支援自動收集功能的應用程式與應用程式傳送事件 (例如資訊站、手錶等)

運送（查詢參數）

運送，官方幫助裡有時候也叫查詢參數，就是傳送資料的位置和方式，如https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}，一定要加上密鑰值和評估ID

參數名稱	說明
`api_secret`	必填。透過 Google Analytics (分析) 使用者介面產生的 `API Secret`。如要建立新密鑰，請在 Google Analytics (分析) UI 中前往以下位置：管理員 > 資料串流 > 選擇串流 > Measurement Protocol > 建立因此，建議您只在貴機構中公開這些資料。如果您在用戶端部署 Measurement Protocol，應定期輪替 `api_secret`，以避免過度處理。
`firebase_app_id`	必填。Firebase 應用程式 ID。Firebase 應用程式的 ID。可在 Firebase 控制台中找到：專案設定 > 一般 > 您的應用程式 > 應用程式 ID
`measurement_id`	評估 ID。資料串流的 ID。Google Analytics (分析) UI 位於：管理員 > 資料串流 \| 選擇串流 > 評估 ID

酬載（訊息內文）

酬載，官方幫助裡有時候也叫訊息內文，就是傳送你的資料，關於酬載各參數的解釋函義如下：

金鑰	類型	說明
`app_instance_id`	`string`	必填。用於識別 Firebase 應用程式的特定安裝項目，這個值必須透過 Firebase SDK 擷取。這與網站 `client_id` 不同
`client_id`	`string`	必填。唯一識別網路用戶端的使用者執行個體。
`user_id`	`string`	選用，使用者的專屬 ID。如要進一步瞭解這個 ID，請參閱 User-ID 進行跨平台分析。 `user_id` 只能包含 utf-8 字元。
`timestamp_micros`	`number`	選用，與事件建立關聯的 Unix 時間戳記 (以微秒為單位)。此設定只能用來記錄過去發生的事件。這個值可以透過 `user_property` 或事件時間戳記覆寫。根據資源的時區，活動最多可以回溯至 3 天。這個值應以 micro 秒為單位，而非毫秒秒。
`user_properties`	`object`	選用，評估的使用者屬性。詳情請參閱使用者屬性。
`non_personalized_ads`	`boolean`	選用，設為 `true` 表示這些事件不應用於個人化廣告。
`events[]`	`array`	必填。事件項目陣列。每項要求最多可以傳送 25 個事件。請參閱所有有效事件的事件參考資料。
`events[].name`	`string`	必填。事件的名稱。查看所有選項的事件參考資料。
`events[].params`	`object`	選用，事件的參數。請參閱事件，瞭解每個事件的建議參數。

酬載有如下限制：

要求最多可有 25 個事件。
事件最多只能有 25 個參數。
事件最多只能有 25 個使用者屬性。
使用者屬性的名稱不能超過 24 個半形字元。
使用者屬性的值不能超過 36 個半形字元。
事件名稱不能超過 40 個字元，只能使用英文字母、數字和底線，且必須以字母為開頭。
參數名稱 (包括項目參數) 不能超過 40 個字元，只能使用英文字母、數字和底線，且必須以字母為開頭。
參數值 (包括項目參數值) 不能超過 100 個字元。
項目參數最多只能有 10 個自訂參數。
訊息內文必須小於 130 KB。

Measurement Protocol和Measurement Protocol API的區別

Measurement Protocol是通用版GA的叫法，Measurement Protocol API是GA4中叫法，Measurement Protocol API是Measurement Protocol是升級版，目前GA4中的Measurement Protocol API有如下優勢：

密鑰值：有密鑰值，有效減少機器流量
更大的酬載：GA4的Measurement Protocol最大酬載是130KB，通用版的Measurement Protocol最大酬載是16KB
GA4 的 Measurement Protocol API 僅支援 POST 要求。

但現在GA4中逐漸直接用Measurement Protocol取代Measurement Protocol API，後面文章中的Measurement Protocol指代Measurement Protocol API。

Measurement Protocol API 案例演示

假設要傳送 tutorial_begin 事件。

GA4中創建Measurement Protocol密鑰

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

在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"
   }
 ]
}

驗證事件

接下來就是驗證這個事件：

如果收到 HTTP 要求，Measurement Protocol 一律會傳回 2xx 狀態碼。如果酬載資料格式錯誤、酬載中的資料不正確或未由 Google Analytics (分析) 處理，Measurement Protocol 則不會傳回錯誤代碼。

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

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

點擊VALIDATE EVENT去驗證：

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

驗證導入狀態

那麼可以返回到GA4中的即時報表中，可以在事件計數裡看到事件 tutorial_begin

常見問題：MP協議發送的事件歸因錯誤

如果你按照官方幫助去發送MP資料，那麼在GA4中看數據的時候會發現，MP協議傳送的的事件都劃分到not set，都歸因錯誤。

這是因為缺少engagement_time_msec 和 session_id，雖然這兩個參數是可選的，但如果要在報告中準確歸因，那麼就是必須的。

如果還出現not set，那就是時間問題，GA4只能處理3天內的數據，也就是超過3天的數據，在發送過去，是歸因不了的。

延伸閱讀：GA4 Measurement Protocol 常見問題（2023）

如果您在操作上仍有任何疑問，歡迎留言交流，或加入：Google Analytics 4交流社團發問