Skip to content

GA4 Measurement Protocol API 使用教學與應用範例

什麼是 Measurement Protocol API?

GA4 Measurement Protocol(以下簡稱 MP),是一個標準通訊協定,可以將數據以 HTTP POST 形式把 GA4 事件直接送到指定 GA 資源, MP 通常用於收集/整合線下產生的數據(包含線下交易、定期購買、第三方 CRM 數據等等);如果只要收集 Web、APP 數據,使用正常代碼導入方式即可。

事實上,在通用版 GA 就有 MP 的存在,兩者最大的差異在於,通用版 GA MP 只需要取得資源編號,就可以向 GA 傳送數據,而資源編號可以輕易的在網頁上查詢,這會導致任何人都可以向你的資源發送垃圾數據,包括你的競爭對手; GA4 MP 新增了 API 密鑰功能,使用 MP 必須搭配資源產生的 API 密鑰才能向 GA4 傳送數據,主要就是為了阻擋垃圾數據的產生。

GA4 Measurement Portocol 使用說明

通用版 GA MP vs GA4 MP

GA4 MP 算是通用版 GA MP 的更新版,提供更安全與方便的功能環境,下圖為兩者的差異比較:

通用版 GA MP vs Google Analytics 4 Measurement Protocol

伺服器位置

GA4 MP 提供以下兩種伺服器位置:

  1. https://www.google-analytics.com/mp/collect
    • 正式伺服器,傳送的數據會進入 GA4 資源,通訊協定有誤時,不會出現錯誤警告
  2. https://www.google-analytics.com/debug/mp/collect
    • 驗證用伺服器,傳送的數據不會進入 GA4 資源,通訊協定有誤時,會出現錯誤警告

由於 GA4 MP 通訊協定較為複雜,如果傳送錯誤代碼格式訊號,可能導致 GA4 無法接收數據;有了驗證伺服器,可以幫助找出錯誤位置;正式傳送數據前,建議先使用驗證伺服器檢查傳送代碼格式是否正確(下面會介紹使用方式)。

MP 資料結構

MP 資料結構主要由以下5種主要參數組成:資料串流 MP API 密鑰資料 ID (Web 評估 ID or APP app ID)、裝置 ID (Web client_id or APP app_instance_id)、事件名稱事件參數;其中,資料串流 MP API 密鑰與資料串流 ID 會儲存在網址查詢參數,其餘參數則以 JSON 格式儲存,下方為 Web MP 資料結構範例:

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${資料 ID}&api_secret=${資料串流 MP API 密鑰}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: 'XXXXXXXXXX.YYYYYYYYYY',	//裝置 ID
    events: [{
      name: 'tutorial_begin',		//事件名稱
      params: {
	pr1:'事件參數1',			//事件參數
	pr2:'事件參數2'			//事件參數
	}		
    }]
  })
});

查詢參數介紹

先前有提到,查詢參數只會包含資料 ID資料串流 MP API 密鑰兩個資訊,跟著下面步驟,取得這兩個參數值:

取得資料 ID

注意:資料 ID 不是資料串流 ID!

-Web 資料 ID(評估 ID)

取得 GA4 Web 評估 ID

前往資源 -> Web 資料串流 -> 複製評估 ID

-APP 資料 ID(Firebase 應用程式 ID)

取得 GA4 應用程式 APP ID

前往資源 -> APP 資料串流 -> 複製 Firebase 應用程式 ID

取得 Measurement Protocol API 密鑰

GA4 MP API 密鑰由資料串流層級產出,不同資料串流需要分別建立各自的 API 金鑰,依照下方步驟建立並取得 API 密鑰(Web 和 APP 資料串流建立方式相同)。

建立 Google Analytics 4 MP API 密鑰

前往資源 -> 資料串流 -> 選擇要使用 MP API 的資料串流 -> 點擊 Measurement Protocol API 密鑰

建立 GA4 Measurement Protocol API 密鑰

點擊右上方建立,給予密鑰一個暱稱(辨識用,不影響後續設定),取得資料串流 API 密鑰值。

JSON 參數格式介紹

先前有提到,除了 MP API 密鑰資料 ID 使用網址查詢參數儲存,其餘參數會以 JSON 格式儲存,下圖為 GA4 MP 支援的參數:

Google Analytics 4 Measurement Protocol 支援 參數 (JSON)

參數限制

使用 GA4 MP 傳送事件時,一樣要遵守 GA4 對於事件的規範,包含限制與用量以及避免使用保留名稱

應用範例

接下來將使用瀏覽器 Console 配合 GA4 MP 傳送測試事件到 GA4 資源。

傳送單一事件 – 正確代碼格式

下方為範例代碼,傳送 “test_event” 事件到 GA4,正式傳送以前,先使用驗證伺服器確認代碼格式是否正確。

fetch(`https://www.google-analytics.com/debug/mp/collect?measurement_id=G-4E2F5EFRMF&api_secret=aoOKXLh5Tf6Gf5IU-zJAVw`, {
  method: "POST",
  body: JSON.stringify({
    client_id: '111.111',
    events: [{
      name: 'test_event',
      params: {
	pr1:'事件參數1',
	pr2:'事件參數2'
	}
    }]
  })
}).then(response => response.json())
  .then(data => console.log(data));
GA4 單一事件 MP 驗證伺服器

傳送 MP 到驗證伺服器後,伺服器會回傳驗證訊息,顯示 {validationMessages: Array(0)} 表示代碼格式無誤,可以進行下一步,將事件傳送到正式伺服器。

GA4 單一事件 MP 數據驗證

使用 MP 傳送事件後,在 GA4 資源即時報表,即可看到先前傳送的 “test_event” 事件出現在報表上。

傳送單一事件 – 錯誤代碼格式

下方為範例代碼,傳送 “user_engagement” 事件到 GA4(user_engagement 為系統保留事件名稱,不能使用),正式傳送以前,先使用驗證伺服器確認代碼格式是否正確。

fetch(`https://www.google-analytics.com/debug/mp/collect?measurement_id=G-4E2F5EFRMF&api_secret=aoOKXLh5Tf6Gf5IU-zJAVw`, {
  method: "POST",
  body: JSON.stringify({
    client_id: '111.111',
    events: [{
      name: 'user_engagement'
    }]
  })
}).then(response => response.json())
  .then(data => console.log(data));
GA4 單一事件 錯誤格式 驗證伺服器

傳送 MP 到驗證伺服器後,伺服器會回傳驗證訊息,顯示 {validationMessages: Array(1)} 表示代碼格式有發現異常,將回傳訊息展開查看異常資訊。

GA4 單一事件 錯誤格式 錯誤警告

異常警告顯示 “user_engagement” 事件名稱為系統保留事件,無法使用;異常警告主要分為以下三個欄位:

  • description
    • 對於異常警告的描述。
  • fieldPath
    • 發現異常的位置。
  • validationCode
    • 異常警告代碼。

完整的異常警告說明清單可以參考官方文件

傳送複數事件

下方為範例代碼,同時傳送 “test_event” 和 “test_event1” 事件到 GA4,正式傳送以前,先使用驗證伺服器確認代碼格式是否正確。

fetch(`https://www.google-analytics.com/debug/mp/collect?measurement_id=G-4E2F5EFRMF&api_secret=aoOKXLh5Tf6Gf5IU-zJAVw`, {
  method: "POST",
  body: JSON.stringify({
    client_id: '111.111',
    events: [{
      name: 'test_event',
      params: {
	pr1:'事件參數1',
	pr2:'事件參數2'
	}
    },{
      name: 'test_event1',
      params: {
	pr1:'事件參數1',
	pr2:'事件參數2'
	}
    }]
  })
}).then(response => response.json())
  .then(data => console.log(data));
GA4 複數事件 MP 驗證伺服器

傳送 MP 到驗證伺服器後,伺服器會回傳驗證訊息,顯示 {validationMessages: Array(0)} 表示代碼格式無誤,可以進行下一步,將事件傳送到正式伺服器。

GA4 複數事件 MP 數據驗證

使用 MP 傳送事件後,在 GA4 資源即時報表,即可看到先前傳送的 “test_event” 和 “test_event1” 事件出現在報表上。

GA4 Event Builder

除了透過代碼傳送 MP 以外, Google 也提供了 GA4 MP 專用 Event Builder 工具,可以在介面上完成 MP 設定、驗證與傳送步驟,將數據送到 GA4 資源。

GA4 event builder

結語

儘管 GA4 MP 提供了更安全與方便的功能環境,但目前仍屬於 alpha 測試階段,無法保證產品穩定性,不建議現階段將此功能納入正式商業用途,使用前請先了解目前已知有可能發生的問題

數據顧問服務

數據酷顧問團隊
提供企業專屬的數據解決方案

文章許願池

想看什麼文章主題?
我們會儘快為您安排

數據顧問服務

數據酷顧問團隊
提供企業專屬的數據解決方案

文章許願池

想看什麼文章主題?
我們會儘快為您安排

數據顧問服務

數據酷顧問團隊
提供企業專屬的數據解決方案

文章許願池

想看什麼文章主題?
我們會儘快為您安排

Scroll To Top