文章分類
報表範本
追蹤粉絲專頁
GA4 分析報表範本
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 的更新版,提供更安全與方便的功能環境,下圖為兩者的差異比較:
伺服器位置
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 支援的參數:
參數限制
使用 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));
傳送 MP 到驗證伺服器後,伺服器會回傳驗證訊息,顯示 {validationMessages: Array(0)} 表示代碼格式無誤,可以進行下一步,將事件傳送到正式伺服器。
使用 MP 傳送事件後,在 GA4 資源即時報表,即可看到先前傳送的 “test_event” 和 “test_event1” 事件出現在報表上。
GA4 Event Builder
除了透過代碼傳送 MP 以外, Google 也提供了 GA4 MP 專用 Event Builder 工具,可以在介面上完成 MP 設定、驗證與傳送步驟,將數據送到 GA4 資源。
結語
儘管 GA4 MP 提供了更安全與方便的功能環境,但目前仍屬於 alpha 測試階段,無法保證產品穩定性,不建議現階段將此功能納入正式商業用途,使用前請先了解目前已知有可能發生的問題。
數據顧問服務
文章許願池
想看什麼文章主題?
我們會儘快為您安排
數據顧問服務
文章許願池
想看什麼文章主題?
我們會儘快為您安排
數據顧問服務
文章許願池
想看什麼文章主題?
我們會儘快為您安排