將 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/Google 代碼管理工具) 應用程式串流 (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 用於驗證您的要求。請務必妥善保管這個密鑰。

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

  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. 按一下「專案總覽」旁的設定齒輪圖示，然後選取「專案設定」。
  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

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

  • 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 擷取該 ID，請參閱應用程式執行個體 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 會為 tutorial_begin 和 join_group 事件以及 customer_tier 使用者屬性指派 requestUnixEpochTimeInMicros 的時間戳記。

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

下列範例會傳送要求層級時間戳記、事件層級時間戳記和使用者屬性層級時間戳記。因此，數據分析 (Measurement Protocol) 會指派下列時間戳記：

  • tutorialBeginUnixEpochTimeInMicros參加tutorial_begin賽事
  • customerTierUnixEpochTimeInMicros (目標使用者屬性：customer_tier)
  • requestUnixEpochTimeInMicros 事件和 newsletter_reader 使用者屬性。join_group
{
  "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 時，有下列限制：

  • 要求最多只能有 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 有幾個預留名稱，不能用於事件、參數或使用者屬性。

以下是容易混淆的事件名稱：

如要瞭解各用途的額外需求，請參閱常見用途。