Measurement Protocol 伺服器位置

GA4 MP 提供以下兩種伺服器位置： https://www.google-analytics.com/mp/collect 正式伺服器，傳送的數據會進入 GA4 資源，通訊協定有誤時，不會出現錯誤警告。 https://www.google-analytics.com/debug/mp/collect 驗證用伺服器，傳送的數據不會進入 GA4 資源，通訊協定有誤時，會出現錯誤警告。

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

最後更新日期 2021 年 7 月 23 日|Google Analytics 4

什麼是 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 提供以下兩種伺服器位置：

https://www.google-analytics.com/mp/collect
- 正式伺服器，傳送的數據會進入 GA4 資源，通訊協定有誤時，不會出現錯誤警告。
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）

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

-APP 資料 ID（Firebase 應用程式 ID）

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

取得 Measurement Protocol API 密鑰

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

前往資源 -> 資料串流 -> 選擇要使用 MP API 的資料串流 -> 點擊 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));

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

使用 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));

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

異常警告顯示 “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));