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

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

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

格式化要求

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

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

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

PAYLOAD_DATA

請務必在要求 URL 中包含下列項目：

api_secret：Google Analytics 使用者介面產生的 API 密鑰。

如要建立新的密鑰，請依序前往「管理」 >「資料收集和修改」 >「資料串流」 >「選擇所需串流」 >「Measurement Protocol API 密鑰」 >「建立」。

measurement_id：與串流相關的評估 ID，可前往 Google Analytics 使用者介面的以下位置查看：「管理」 >「資料串流」 > 選擇串流 >「評估 ID」。

measurement_id 不是串流 ID。

如需完整參考資料，請參閱查詢參數。

請務必在要求內容中包含下列項目：

client_id：用戶端的專屬 ID。這與 Firebase app_instance_id 不同。請使用 gtag.js('get')。

user_id：選用。使用者的專屬 ID，只能包含 UTF-8 字元。如要進一步瞭解這個 ID，請參閱「跨平台分析的 User-ID」。
consent：選用。瞭解如何設定同意聲明設定。
user_location：選用。要求中事件的地理資訊。
ip_override：選用。Google Analytics 應從中衍生要求中事件的地理位置資訊的 IP 位址。

如果要求也包含 user_location，Google Analytics 就會忽略這個欄位。
device：選用。要求中事件的裝置資訊。

timestamp_micros：選用。要求中事件和使用者屬性的 Unix 紀元時間 (以微秒表示)。如未指定，則預設為要求的時間。
events：事件項目陣列。可在一個要求中包含多個事件。

如要在特定報表 (例如即時報表) 中顯示使用者活動，則務必在event的 params 中附上 engagement_time_msec 和 session_id。engagement_time_msec 參數應反映事件的參與時間 (以毫秒表示)。

範例如下：

  {
   "client_id": "CLIENT_ID",
   "events": [
     {
        "name": "campaign_details",
        "params": {
          "campaign_id": "google_1234",
          "campaign": "Summer_fun",
          "source": "google",
          "medium": "cpc",
          "term": "summer+travel",
          "content": "logolink",
          "session_id": "123",
          "engagement_time_msec": 100
        }
     }
   ]
  }

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

立即試用

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

const measurementId = "MEASUREMENT_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: "CLIENT_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"
    }
  })
});

覆寫時間戳記

Measurement Protocol 會使用下列清單中找到的第一個時間戳記，做為要求中每個事件的時間戳記：

活動的 timestamp_micros。
要求的 timestamp_micros。
Measurement Protocol 收到要求的時間。

以下範例會傳送要求層級的時間戳記，適用於要求中的所有事件。因此，Measurement Protocol 會為 tutorial_begin 和 join_group 事件指派 requestUnixEpochTimeInMicros 的時間戳記。

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

下列範例會同時傳送要求層級時間戳記和事件層級時間戳記。因此，Measurement Protocol 會為tutorial_begin事件指派 tutorialBeginUnixEpochTimeInMicros 的時間戳記，並為join_group事件指派 requestUnixEpochTimeInMicros 的時間戳記。

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ]
}

限制

透過 Measurement Protocol 將事件傳送至 Google Analytics 時，有下列限制：

要求最多可包含 25 個事件。
事件最多只能有 25 個參數。
事件最多只能有 25 個使用者屬性。
使用者屬性的名稱不能超過 24 個半形字元。
使用者屬性的值不能超過 36 個半形字元。
事件名稱不能超過 40 個半形字元，只能使用英文字母、數字和底線，且必須以字母為開頭。
參數名稱 (包括項目參數) 不能超過 40 個半形字元，只能使用英文字母、數字和底線，且必須以字母為開頭。
參數值 (包括項目參數值) 不能超過 100 個半形字元 (標準 Google Analytics 資源) 或 500 個半形字元 (Google Analytics 360 資源)。
項目參數最多可有 10 個自訂參數。
貼文內容不得超過 130 KB。
傳送至 Google Analytics 的應用程式 Measurement Protocol 事件，不會在 Google Ads 中為應用程式使用者填入搜尋目標對象。

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