目標對象匯出基礎知識

Google Analytics (分析) 4 目標對象可讓您根據自家業務的需求區隔使用者。透過目標對象,您可以根據共用的屬性,將網站或應用程式的使用者分組。

您可以使用 Google Analytics (分析) Data API v1 產生目標對象匯出項目,其中包含目標對象使用者的數據匯報。

建立目標對象匯出項目

Google Analytics (分析) Data API v1 是以非同步的方式建立目標對象匯出項目。首先,您必須向 audienceExports.create 方法發出要求,才能建立使用者匯出的目標對象。接著,使用 audienceExports.query 方法擷取目標對象的使用者。

此外,您可以使用 audienceExports.get 擷取特定目標對象匯出作業的設定中繼資料,並使用 audienceExports.list 列出資源的所有目標對象匯出項目。

選取報表實體

凡是 Data API v1 的方法,都必須在網址要求路徑內以 properties/GA4_PROPERTY_ID 的格式指定 Google Analytics (分析) 4 資源 ID,例如:

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/audienceExports

系統會根據指定 Google Analytics (分析) 4 資源中收集到的 Google Analytics (分析) 事件資料產生報表。

如果您使用的是其中一個 Data API 用戶端程式庫,就不需要手動操控要求網址路徑。多數 API 用戶端都會提供 property 參數,這個參數表示字串格式為 properties/GA4_PROPERTY_ID。如需用戶端程式庫使用範例,請參閱快速入門指南

要求建立目標對象匯出項目

如要建立目標對象匯出作業,請使用要求中的 AudienceExport 物件呼叫 audienceExports.create 方法。以下是必要參數:

  • audience 欄位中的有效目標對象名稱,格式為 properties/{propertyId}/audiences/{audienceId}。您可以使用 Google Analytics Admin API v1 的 audiences.list 方法取得這個值。audiences.list 回應的 Audience.name 欄位包含目標對象名稱。
  • dimensions 欄位中的有效維度清單。如需此方法支援的維度清單,請參閱目標對象匯出結構定義說明文件。 目標對象匯出只會包含這個欄位中提到的維度資料。

目標對象匯出建立要求範例:

HTTP 要求

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

audienceExports.create 方法的回應會在 name 欄位中包含目標對象匯出名稱 (例如 properties/1234567/audienceExports/123),可用於後續查詢,從目標對象匯出項目中擷取使用者。

HTTP 回應

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceExport",
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "CREATING",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  }
}

查詢目標對象匯出完備性狀態

呼叫 audienceExports.create 後,產生目標對象匯出可能需要幾分鐘的時間。您可以呼叫 audienceExports.get 方法來取得目標對象匯出項目的完備性狀態。

使用您在 audienceExports.create 回應中提供的目標對象匯出名稱 (例如 properties/1234567/audienceExports/123) 指定目標對象匯出。

示例:

HTTP 要求

GET https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123

目標對象匯出的完備性狀態會在回應的 state 欄位中傳回。目標對象匯出產生完成後,狀態會從 CREATING 變更為 ACTIVE

HTTP 回應

{
  "name": "properties/1234567/audienceExports/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "state": "CREATING",
  "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
}

您可以呼叫 audienceExports.list 方法,取得所有目標對象匯出項目的狀態。

在目標對象匯出中擷取使用者

使用 audienceExports.create 方法產生目標對象匯出項目後,請呼叫 audienceExports.query 方法,並指定目標對象匯出名稱 (例如 properties/1234567/audienceExports/123)。

HTTP 要求

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

目標對象匯出準備就緒時,系統會傳回包含目標對象使用者清單的回應:

HTTP 回應

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}

目標對象匯出資料預期

下節將針對目標對象匯出中的使用者設定資料期望。

資料更新間隔

「目標對象匯出」資料更新間隔,是指 Google Analytics (分析) 收集事件、處理事件,然後在目標對像中更新使用者成員資格所需的時間。如果這個流程需時 24 小時,則目標對象匯出資料的更新間隔就是 24 小時。詳情請參閱資料更新間隔一文。

舉例來說,如果使用者完成第一筆購物交易,而之後 7 小時您建立「購買者」目標對象的目標對象匯出,那麼使用者幾乎肯定不在「購買者」目標對象匯出中。初次購買後的 14 到 38 小時內,該使用者可能會納入新的目標對象匯出項目。

目標對象匯出為數據匯報

目標對象匯出項目是快照中特定目標對象的使用者名單。針對 Google Ads 再行銷,Google Analytics (分析) 會自動並持續將目標對像中的使用者匯出至 Google Ads。相對的,使用 Data API v1 建立的目標對象匯出功能,必須建立新的目標對象匯出項目,才能查看該目標對像中的最新使用者。

目標對象匯出內容是根據可用的最新使用者成員資格建立。然而,目標對象匯出項目的資料更新間隔可能為 20 小時,這表示目標對象匯出將以目前時間點之前 20 小時的所有事件為依據。

最新的會員資料每天會更新一次,通常在資源所在時區的日光時段內。也就是說,如果在上午 9 點和上午 11 點對相同目標對象執行目標對象匯出作業,可能會傳回相同的資料,但下午 3 點的目標對象匯出則可能因加入額外的當天資料而有所不同。

目標對象匯出過期

目標對象匯出項目會在 72 小時後失效。新使用者每天可能會進入及退出目標對象。如要取得最新的使用者數據匯報,您需要每天建立新的目標對象匯出。

目標對象匯出使用者限制

如果目標對像或資源的大小超過使用者限制,目標對象匯出功能會傳回代表的目標對象樣本。 這些限制取決於您的資源類型 (即標準或 360 資源),且會分別在每個目標對象匯出作業中強制執行。 回訪的使用者是指所要求目標對象的使用者,而系統視為的使用者不一定是該目標對象的成員。

限制類型 標準資源限制 Analytics (分析) 360 資源限制
回訪者數量上限 200 萬 2 億
考慮到的使用者人數上限 1000 萬 10 億

報表識別資訊一致性

報表識別資訊可決定報表中簡化使用者的方式。目標對象匯出項目不會因報表識別資訊設定而變更。 目標對象匯出項目一律會依據 User-ID 和裝置 ID 識別使用者。

這表示,目標對象報表所顯示的使用者人數可能超過「目標對象匯出工具」的傳回值。舉例來說,如果報表識別資訊是「以裝置為基礎」,並且收集了 User-ID,報表就不會根據使用者 ID 刪除重複的使用者,但目標對象匯出功能會根據使用者 ID 刪除重複的使用者。

此外,目標對象報表中顯示的使用者人數也可能少於目標對象匯出報表傳回的使用者人數。舉例來說,如果報表識別資訊為「混合」,報表會根據 Google 信號刪除重複的使用者,但目標對象匯出項目不會。

補充作業一致性

如果您在 Google Analytics (分析) 中建立目標對象,並啟用 Google Ads 再行銷,Google Analytics (分析) 就會將近期新增的成員回補至 Google Ads 中的該目標對象。不過,Google Analytics (分析) 報表和目標對象匯出項目「不包含」回補的目標對象成員。建立目標對象後,使用者必須記錄事件,報表和目標對象匯出功能才會顯示該目標對像中的使用者。

舉例來說,如果使用者在 6 月 20 日記錄購買事件,而您在 6 月 21 日建立「購買者」目標對象,可能要等到 6 月 22 日才能在新的目標對象匯出項目中看到該使用者。但是,只有在使用者於 6 月 21 日記錄任何事件的情況下,該使用者才會出現在目標對象匯出結果中。