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 主體。

查詢參數

JSON POST 主體

JSON POST 主體的大小必須小於 130 KB。

常見事件參數

Measurement Protocol 包含下列常見事件參數：

同意聲明

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

地理位置資訊

user_location 和 ip_override 屬性提供地理資訊。user_location 的優先順序高於 ip_override。

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

以下是 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 會使用app_instance_id，從標記事件衍生出地理資訊。

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

裝置資訊

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

以下程式碼片段為 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"
}

無論您指定device、，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_