Measurement Protocol 參考資料

本頁說明 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 或事件時間戳記覆寫。事件最多可回溯 72 小時。

user_properties

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

user_data

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

non_personalized_ads

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

user_location

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

ip_override

 string (選用) Google Analytics 用來推導要求地理區域資訊的 IP 位址。

device

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

validation_behavior

 string

(選用步驟) 為要求設定驗證行為。

可以是 RELAXED 或 ENFORCE_RECOMMENDATIONS。如未指定，則預設值為 RELAXED。

events[]

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

events[].name

 string 必填。活動名稱。如要瞭解所有選項，請參閱「事件」。

events[].params

 object (選用) 事件的參數。請參閱「事件」 一文，瞭解各個事件的建議參數，以及「常見事件參數」。

常見事件參數

Measurement Protocol 具有下列常見的事件參數：

鍵 類型 說明

session_id

 number 識別使用者工作階段的正數。這是常見用途的必要條件。必須符合規則運算式 ^\d+$。

engagement_time_msec

 number 事件的使用者參與時間長度 (以毫秒為單位)。使用的值應反映自前一個事件以來的使用者參與時間量。

timestamp_micros

 number 事件的 Unix 紀元時間 (以微秒表示)。使用這個參數覆寫事件的時間戳記。

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 都會將資源的精細裝置資料設定套用至要求。

驗證行為

validation_behavior 屬性會控管 Measurement Protocol 驗證要求內容的方式。

  • RELAXED 驗證只會拒絕格式錯誤的要求。系統可能仍會接受欄位名稱無效或資料類型不正確的事件和參數，但會忽略超出限制的參數。根據預設，Measurement Protocol 會使用 RELAXED 驗證。
  • ENFORCE_RECOMMENDATIONS驗證會拒絕類型不正確的事件和商品參數，或包含超出限制的參數。此外，ENFORCE_RECOMMENDATIONS 會拒絕任何時間戳記不在過去 72 小時內的事件或使用者屬性。

建議您採取下列做法：

  • 驗證事件時，請使用 ENFORCE_RECOMMENDATIONS，盡可能取得有關要求潛在問題的回饋。

    您也可以使用事件建立工具驗證要求，因為該工具會在驗證要求時指定 ENFORCE_RECOMMENDATIONS。

  • 傳送事件時請勿指定 validation_behavior，以免 Measurement Protocol 拒絕資料。

    如要在傳送特定要求時，優先進行嚴格驗證而非資料收集，請新增 validation_behavior 欄位並設為 ENFORCE_RECOMMENDATIONS。

自訂參數

您可以在 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
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

此外，ad_impression、in_app_purchase 和 screen_view 事件僅適用於應用程式串流。

保留參數名稱

以下是保留的參數名稱，無法使用：

  • 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_