Measurement Protocol 參考資料

總覽

使用 Measurement Protocol 將資料傳送至 Google Analytics 的程序分為兩個部分：

  1. 傳輸：傳送資料的位置和方式
  2. 酬載：您傳送的資料

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

運輸

網址端點

您可以透過向下列端點發出 HTTP POST 要求，使用 Measurement Protocol 傳送資料：

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 使用者介面產生的 API Secret。

如要建立新的密鑰，請在 Google Analytics UI 中依序前往：
「管理」 >「資料串流」 > 選擇所需串流 >「Measurement Protocol」 >「建立」

建議你只讓貴機構的使用者存取這些資訊。如果您部署評估通訊協定用戶端，應定期輪替 api_secret，以免產生過多垃圾郵件。

JSON 貼文內文

鍵 類型 說明

user_id

 string

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

timestamp_micros

 number

選用設定。與事件相關聯的時間，以 Unix 時間戳記 (以微秒為單位) 表示。這項設定只應用於記錄過去發生的事件。您可以透過 user_property 或事件時間戳記覆寫這個值。事件可根據資源所在時區，回溯至最多 3 個日曆天。

user_properties

 object 選用設定。評估的使用者屬性。詳情請參閱「使用者屬性」。

user_data

 object 選用設定。使用者提供的資料。詳情請參閱使用者提供資料指南。
object 選用設定。設定要求的同意聲明設定。詳情請參閱同意聲明部分。

non_personalized_ads

 boolean 選用設定。將其設為 true，表示不應使用使用者資料放送個人化廣告。

events[]

 array 必填。事件項目的陣列。每個要求最多可傳送 25 個事件。如要瞭解所有有效事件，請參閱「事件」參考資料。

events[].name

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

events[].params

 object 選用設定。事件的參數。如要瞭解每個事件的建議參數，請參閱事件。

consent 屬性會設定同意聲明類型和狀態。如果您未指定 consent，Google Analytics 會使用用戶端或應用程式執行個體對應線上互動內容的同意聲明設定。

鍵 類型 說明

ad_user_data

 string

選填。設定同意聲明狀態，指明可否基於廣告用途，將要求的事件和使用者屬性中的使用者資料傳送給 Google。

必須是 GRANTED 或 DENIED。

ad_personalization

 string

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

必須是 GRANTED 或 DENIED。

自訂參數

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

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

部分事件有建議參數。如要瞭解所有支援事件的建議參數，請參閱「事件」。

保留名稱

預留事件名稱

以下是保留的事件名稱，無法使用：

  • ad_activeview
  • ad_click
  • ad_exposure
  • 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
  • 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_