Measurement Protocol 參考資料

總覽

使用 Measurement Protocol 將資料傳送至 Google Analytics (分析) 有兩個部分:

  1. 傳輸 - 傳送資料的地點和方式
  2. 酬載 - 您傳送的資料

本文件說明傳輸和酬載的格式。

運輸

網址端點

您可以使用 Measurement Protocol 傳送資料,方法是向下列端點發出 HTTP POST 要求:

https://www.google-analytics.com/mp/collect

如要傳送事件,請發出下列 POST 要求:

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
<payload_data>
  • 要求的 BODY。請參閱「酬載」一節。

回應碼

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

酬載

使用 Measurement Protocol 資料傳送至 Google Analytics (分析) 時,分為兩部分:

  1. 查詢參數
  2. JSON POST 主體

查詢參數

參數名稱 說明

api_secret

必要。透過 Google Analytics (分析) UI 產生的 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

JSON 文章內文

類型 說明

app_instance_id

string

必要。專門用於識別 Firebase 應用程式的特定安裝項目。必須透過 Firebase SDK 擷取這個值。

client_id

string

必要。用於識別網路用戶端的使用者執行個體。 請參閱「將事件傳送至 Measurement Protocol」一節。

user_id

string

選用設定。使用者的專屬 ID。如要進一步瞭解這個 ID,請參閱「跨平台分析的 User-ID」。

timestamp_micros

number

選用設定。要與事件建立關聯的時間 Unix 時間戳記 (以微秒為單位)。建議您只用於記錄過去發生的事件。您可以透過 user_property 或事件時間戳記覆寫這個值。根據資源的時區,事件最多可以回溯到 3 天內。

user_properties

object 選用設定。評估的使用者屬性。詳情請參閱「使用者屬性」一文。
object 選用設定。設定請求的同意聲明設定。詳情請參閱同意聲明一節

non_personalized_ads

boolean 選用設定。設為 true,表示不得將使用者的資料用於個人化廣告。

events[]

array 必要。事件項目的陣列。每項要求最多可以傳送 25 個事件。如要查看所有有效事件,請參閱事件參考資料。

events[].name

string 必要。事件的名稱。如需所有選項,請參閱事件參考資料。

events[].params

object 選用設定。事件的參數。請查看事件,瞭解每個事件的建議參數。

consent 屬性會設定 consent 類型和狀態。如未指定 consent,Google Analytics (分析) 就會針對用戶端或應用程式執行個體,使用對應線上互動中的同意聲明設定。

類型 說明

ad_user_data

string

選用。設定同意聲明,允許將使用者資料從要求的事件和使用者屬性傳送至 Google,以便用於廣告用途。

必須是 GRANTEDDENIED

ad_personalization

string

選用。針對使用者設定個人化廣告的同意聲明。

必須是 GRANTEDDENIED

自訂參數

除了規定的參數外,您還可以在 Measurement Protocol 酬載中納入以使用者為範圍、以事件為範圍的自訂參數和以商品為範圍的參數

  • 使用者範圍的自訂參數可以納入酬載的 user_properties 物件中。
  • 事件範圍的自訂參數可以納入酬載的 events[].params 物件中。
  • 在每個事件的 items 陣列中,可以加入以商品為範圍的自訂參數

部分事件有建議參數。如需所有支援事件的建議參數,請參閱事件

保留名稱

預留事件名稱

以下是保留的事件名稱,無法使用:

  • ad_activeview
  • ad_click
  • ad_exposure
  • ad_impression
  • ad_query
  • ad_reward
  • adunit_exposure
  • app_clear_data
  • app_exception
  • app_install
  • app_remove
  • app_store_refund
  • app_update
  • app_upgrade
  • dynamic_link_app_open
  • dynamic_link_app_update
  • dynamic_link_first_open
  • error
  • firebase_campaign
  • firebase_in_app_message_action
  • firebase_in_app_message_dismiss
  • firebase_in_app_message_impression
  • first_open
  • first_visit
  • in_app_purchase
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • screen_view
  • session_start
  • user_engagement

保留參數名稱

以下是保留的參數名稱,無法使用:

  • firebase_conversion

此外,參數名稱的開頭不得為:

  • _ (underscore)
  • firebase_
  • ga_
  • google_
  • gtag.

預留使用者屬性名稱

以下是保留的使用者屬性名稱,無法使用:

  • first_open_time
  • first_visit_time
  • last_deep_link_referrer
  • user_id
  • first_open_after_install

此外,使用者屬性名稱的開頭不得為:

  • _ (underscore)
  • firebase_
  • ga_
  • google_