Measurement Protocol 參考資料

本頁說明評估資料通訊機制和評估資料通訊協定中的資料參數。

運輸

所有資料都必須透過 HTTPS POST 要求安全傳送。

將要求傳送至下列端點：

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

如果您希望資料在歐盟境內處理，請改用下列端點：

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

以下是 POST 要求的範例：

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
PAYLOAD_DATA

將 PAYLOAD_DATA 替換為要求的酬載。

如果收到 HTTP 要求，Measurement Protocol 會傳回 2xx 狀態碼。如果酬載格式錯誤，或是資料不正確或未經 Google Analytics 處理，Measurement Protocol 就不會傳回錯誤代碼。

酬載

酬載包含兩個部分：

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

查詢參數

參數名稱 說明

api_secret

 必填。Google Analytics 使用者介面中的 API 密鑰。

依序前往「管理」>「資料串流」 >「選擇串流」>「Measurement Protocol」 >「建立」。

僅限貴機構使用。應定期更新，以免垃圾內容過多。

JSON POST 主體

鍵 類型 說明

user_id

 string

(選用) 使用者的專屬 ID。如要進一步瞭解這個 ID，請參閱「跨平台分析的 User-ID」。只能包含 UTF-8 字元。

timestamp_micros

 number

(選用) 以微秒為單位的 Unix 時間戳記，而非毫秒。代表事件的時間。這項設定應只用於記錄過去發生的事件。可由 user_property 或事件時間戳記覆寫。事件可根據資源的時區，回溯至最多 3 個日曆天。

user_properties

 object (選用) 評估的使用者屬性。

user_data

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

non_personalized_ads

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

user_location

 object (選用) 以結構化格式設定要求的地理資訊。

ip_override

 string (選用) Google Analytics 用來擷取要求地理資訊的 IP 位址。

device

 object (選用步驟) 以結構化格式設定要求的裝置資訊。

events[]

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

events[].name

 string 必填。事件名稱。如需所有選項，請參閱「事件」一文。

events[].params

 object (選用) 事件參數。如要瞭解每個事件的建議參數，請參閱「事件」。

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

鍵 類型 說明

ad_user_data

 string

(選用) 同意將來自要求事件和使用者資源的使用者資料傳送給 Google，用於廣告用途。

GRANTED 或 DENIED。

ad_personalization

 string

(選用) 使用者同意聲明，允許放送個人化廣告。

GRANTED 或 DENIED。

地理位置資訊

user_location 和 ip_override 屬性會提供地理資訊。user_location 優先於 ip_override。

以下是 user_location 欄位的結構。請盡可能提供多項屬性。建議您至少使用 country_id 和 region_id。

鍵 類型 說明

city

 string (選用) 城市名稱。如果城市位於美國，請一併設定 country_id 和 region_id，讓 Google Analytics 能正確將城市名稱對應至城市 ID。

region_id

 string (選用) ISO 3166 國家/地區和子區域。例如：US-CA、US-AR、CA-BC、GB-LND、CN-HK。

country_id

 string (選用) 國家/地區代碼，採 ISO 3166-1 alpha-2 格式。例如：US、AU、ES、FR。

subcontinent_id

 string (選用) 使用 UN M49 格式輸入子洲別。例如：011、021、030、039。

continent_id

 string (選用) UN M49 格式的洲別。例如：002、019、142、150。

以下是 user_location 的範例：

"user_location:" {
  "city:" "Mountain View",
  "region_id:" "US-CA",
  "country_id:" "US",
  "subcontinent_id:" "021",
  "continent_id:" "019"
}

ip_override 是 user_location 的替代方案。如果您改為傳送 ip_override，Google Analytics 會從 IP 位址推斷地理資訊。如果您傳送 user_location，Google Analytics 會忽略 ip_override。

如果您沒有傳送 user_location 或 ip_override，Google Analytics 會使用 client_id。

無論傳送的地理資訊為何，Google Analytics 都會將資源的細微位置資料設定套用至要求。

裝置資訊

如要傳送裝置資訊，請使用 device 欄位。以下是 device 欄位的結構。請盡可能提供多個屬性。建議至少 category。

鍵 類型 說明

category

 string 選填。裝置類別。例如：desktop、tablet、mobile、smart TV。

language

 string 選填。語言代碼，採用 ISO 639-1 格式。例如：en、en-US。

screen_resolution

 string 選填。裝置的解析度，格式為 WIDTHxHEIGHT。例如：1280x2856、1080x2340。

operating_system

 string 選填。作業系統或平台。例如 MacOS。

operating_system_version

 string 選填。作業系統或平台的版本。例如：13.5。

model

 string 選填。裝置型號。例如：Pixel 9 Pro、Samsung Galaxy S24。

brand

 string 選填。裝置品牌。例如：Google、Samsung。

browser

 string 選填。瀏覽器的品牌或類型。例如：Chrome、Firefox。

browser_version

 string 選填。瀏覽器版本。例如：136.0.7103.60、5.0。

以下程式碼片段為 device 設定的範例：

"device:" {
  "category": "mobile",
  "language": "en",
  "screen_resolution": "1280x2856",
  "operating_system": "Android",
  "operating_system_version": "14",
  "model": "Pixel 9 Pro",
  "brand": "Google",
  "browser": "Chrome",
  "browser_version": "136.0.7103.60"
}

無論您指定 ，Google Analytics 都會將資源的細項裝置資料設定套用至要求。

自訂參數

您可以在 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_