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

Google Analytics Haran 3个月前 (11-14) 203次瀏覽 0條留言

這一節來講講GA4中的Measurement Protocol API

什麼是Measurement Protocol API?

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

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

 

Measurement Protocol API包含兩個部分,如下圖:

【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 APIMeasurement Protocol是升級版,目前GA4中的Measurement Protocol API有如下優勢:

但現在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”:

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

就可以獲取密鑰值:

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

  • 密鑰值: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/,接要傳送的資料填進入:

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

然後就可以在下面看到RequestInfo(運送)和Payload(酬載):【GA4設定】用Measurement Protocol API實現離線資料傳送

點擊VALIDATE EVENT去驗證:

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

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

驗證導入狀態

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

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

 

 

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

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

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

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


如果您在操作上仍有任何疑問,歡迎留言交流。

轉載請註明標題:【GA4設定】用Measurement Protocol API實現離線資料傳送
網址鏈接:https://www.haranhuang.com/ga4-measurement-protocol-api.html

Like (0)
發佈我的留言
取消留言
表情 贴图 加粗 删除线 居中 斜体

Hi,*为發佈留言必須填寫。

  • 顯示名稱*
  • 電子郵件地址*
  • 個人網站網址