將 Measurement Protocol 事件傳送至 Google Analytics (分析)

本指南說明如何將 Google Analytics Measurement Protocol 網站和應用程式串流事件傳送至 Google Analytics 伺服器，以便在 Google Analytics 報表中查看 Measurement Protocol 事件。

Measurement Protocol 要求所需的 ID 和參數，取決於您要將事件傳送至網站串流還是應用程式串流。

  • 如果是網站串流 (通常使用 gtag.js 或 Google 代碼管理工具檢測)，請在要求網址中使用 measurement_id，並在 JSON 主體中使用 client_id，以識別使用者執行個體。client_id 應與網站上 Google Analytics 代碼產生的 ID 相符。
  • 如果是應用程式串流 (使用 Firebase SDK 檢測)，請使用要求網址中的 firebase_app_id 和 JSON 主體中的 app_instance_id，這些是由 Google Analytics for Firebase SDK 提供。

本指南提供這兩種情況的範例。

依串流類型區分的重要要求元件

元件 網站串流 (gtag.js/GTM) 應用程式串流 (Firebase)
資料串流網址參數 measurement_id firebase_app_id
API 密鑰網址參數 必填 必填
裝置 ID JSON 主體欄位 client_id app_instance_id

選擇要在本指南中查看的平台：

這個分頁會說明如何使用 Google Analytics for Firebase SDK，從伺服器傳送與應用程式串流中使用者活動相關的事件。請注意，這些要求會使用 firebase_app_id 和 app_instance_id。

必要條件

如要使用 Measurement Protocol 傳送事件，您需要 Google Analytics 資源或 Firebase 專案中的特定 ID。

API 密鑰

api_secret 用於驗證要求。請務必妥善保管這項密鑰。

如要建立新的 Secret，請按照下列步驟操作：

  1. 前往 Google Analytics，然後前往您的帳戶和資源。
  2. 按一下左下方的「管理」。
  3. 在「資料收集和修改」下方，點選「資料串流」。
  4. 選取網站或應用程式資料串流。
  5. 按一下「Measurement Protocol API 密鑰」。
  6. 點選「建立」。
  7. 輸入密鑰的暱稱，然後按一下「建立」。

  8. 複製密鑰值。

Firebase 應用程式 ID

firebase_app_id 用於識別 Firebase 應用程式，與 app_instance_id 不同。

如要找出 Firebase 應用程式 ID，請按照下列步驟操作：

  1. 在 Firebase 控制台中開啟專案。
  2. 按一下「Project Overview」(專案總覽) 旁的「設定」齒輪圖示，然後選取「Project settings」(專案設定)。
  3. 在「一般」分頁中，前往「你的應用程式」部分。
  4. 選取特定的 iOS 或 Android 應用程式。
  5. 複製應用程式 ID 值。

格式化要求

Google Analytics Measurement Protocol 僅支援 HTTP POST 要求。

如要傳送事件，請使用下列格式：

POST /mp/collect?firebase_app_id=<var>FIREBASE_APP_ID</var>&api_secret=<var>API_SECRET</var> HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

請務必在要求網址查詢參數中提供下列項目 (如要瞭解如何尋找或建立這些值，請參閱「必要條件」)：

  • api_secret：用於驗證要求的 API 密鑰。
  • firebase_app_id：應用程式的 Firebase 應用程式 ID。

您必須以 JSON POST 主體格式提供 Measurement Protocol 的要求主體。範例如下：

  {
   "app_instance_id": "APP_INSTANCE_ID",
   "events": [
      {
        "name": "login",
        "params": {
          "method": "Google",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      }
   ]
  }

您必須在要求主體中提供 app_instance_id，以識別行動應用程式的專屬安裝。請注意，這與識別應用程式本身的 firebase_app_id 不同。如要進一步瞭解 app_instance_id，以及如何使用 Firebase SDK 擷取這項資訊，請參閱 app_instance_id 參考文件。

session_start 是預留的事件名稱，建立新的 session_id 會一併建立新的工作階段，不需要再傳送 session_start。瞭解工作階段的計算方式。

試試看

以下範例說明如何一次傳送多個事件。這個範例會將 tutorial_begin 事件和 join_group 事件傳送至 Google Analytics 伺服器，並使用 user_location 欄位加入地理資訊，以及使用 device 欄位加入裝置資訊。

const firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    app_instance_id: "APP_INSTANCE_ID",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 150
        }
      }
    ],
    user_location: {
      city: "Mountain View",
      region_id: "US-CA",
      country_id: "US",
      subcontinent_id: "021",
      continent_id: "019"
    },
    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"
    }
  })
});

firebase_app_id 的格式因平台而異。請參閱「Firebase 設定檔和物件」下方的「應用程式 ID」。

覆寫時間戳記

Measurement Protocol 會在下列清單中，為要求中的每個事件和使用者屬性，找出第一個時間戳記：

  1. 事件或使用者屬性的timestamp_micros。
  2. 要求的 timestamp_micros。
  3. Measurement Protocol 收到要求的時間。

以下範例會傳送要求層級時間戳記，套用至要求中的所有事件和使用者屬性。因此，Measurement Protocol 會將 requestUnixEpochTimeInMicros 的時間戳記指派給 tutorial_begin 和 join_group 事件，以及 customer_tier 使用者屬性。

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin"
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM"
    }
  }
}

以下範例會傳送要求層級時間戳記、事件層級時間戳記，以及使用者屬性層級時間戳記。因此，Measurement Protocol 會指派下列時間戳記：

  • tutorial_begin活動的tutorialBeginUnixEpochTimeInMicros
  • customer_tier 使用者屬性的 customerTierUnixEpochTimeInMicros
  • join_group 事件和 newsletter_reader 使用者屬性的 requestUnixEpochTimeInMicros。
{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ],
  "user_properties": {
    "customer_tier": {
      "value": "PREMIUM",
      "timestamp_micros": customerTierUnixEpochTimeInMicros
    },
    "newsletter_reader": {
      "value": "true"
    }
  }
}

過去事件和使用者屬性的驗證行為

事件和使用者屬性的日期最多可回溯 72 小時。如果 timestamp_micros 值早於 72 小時前，Measurement Protocol 會接受或拒絕事件或使用者屬性，如下所示：

  • 如果未設定 validation_behavior 或設為 RELAXED，Measurement Protocol 會接受事件或使用者屬性，但會將時間戳記覆寫為 72 小時前。
  • 如果 validation_behavior 設為 ENFORCE_RECOMMENDATIONS，Measurement Protocol 會拒絕事件或使用者屬性。

如果使用 Measurement Protocol 傳送的事件，要與 Google Analytics for Firebase SDK 或 gtag.js 收集的事件合併或一併處理，Google Analytics 必須在原始用戶端事件時間戳記的 48 小時內收到這些事件。如果事件晚於這個時間，可能無法按照預期處理，尤其是用於轉換歸因等用途時。

限制

將 Measurement Protocol 事件傳送至 Google Analytics 時，須遵守下列限制：

  • 每個資源每小時最多可傳送 1 億個非轉換要求。如果要求中的事件都不是 Google Ads 轉換的重要事件，則該要求為非轉換要求。如果超過這項限制，Measurement Protocol 會在該小時的剩餘時間內，自動忽略資源的所有非轉換要求。

  • 要求最多可包含 25 個事件。

  • 事件最多只能有 25 個參數。

  • 事件最多只能有 25 個使用者屬性。

  • 使用者屬性的名稱不能超過 24 個半形字元。

  • 使用者屬性的值不能超過 36 個半形字元。

  • 事件名稱不能超過 40 個半形字元，只能使用英數字元和底線，且必須以字母為開頭。

  • 參數名稱 (包括項目參數) 不能超過 40 個半形字元，只能使用英數字元和底線，且必須以字母為開頭。

  • 參數值 (包括項目參數值) 不得超過 100 個半形字元 (標準 Google Analytics 資源) 或 500 個半形字元 (Google Analytics 360 資源)。

    如果 session_id 和 session_number 參數的值是由 Google 代碼管理工具中對應的「Analytics 工作階段 ID」和「Analytics 工作階段編號」內建變數提供，則不適用這項限制。

  • 項目參數最多可有 10 個自訂參數。

  • 貼文內文不得超過 130 KB。

  • 傳送至 Google Analytics 的應用程式 Measurement Protocol 事件，不會填入 Google Ads 中應用程式使用者的搜尋目標對象。

  • 部分事件、參數和使用者屬性名稱為預留名稱，無法使用。詳情請參閱「預留名稱」。

保留名稱

Measurement Protocol 有數個預留名稱，無法用於事件、參數或使用者屬性。

以下事件名稱容易混淆：

如要瞭解各用途的其他規定，請參閱「常見用途」。