本頁面由 Cloud Translation API 翻譯而成。

進階用途

本文件說明 Google Analytics (分析) Data API v1 的幾個進階功能。如需 API 的詳細參考資料，請參閱 API 參考資料。

列出自訂定義及建立報表

Data API 可針對已註冊的自訂維度和自訂指標建立報表。Metadata API 方法可用來列出屬性已註冊自訂定義的 API 名稱。例如，這些 API 名稱可用於對 runReport 方法的報表要求。

以下章節提供各種自訂定義類型的範例。在這些範例中，請將 GA4_PROPERTY_ID 替換成您的資源 ID。

以事件為範圍的自訂維度

步驟 1：使用資源 ID 查詢中繼資料 API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata

步驟 2：找出您想利用回應製作報表的「以事件為範圍」自訂維度。如果沒有維度，則必須登錄維度。

"dimensions": [
...
    {
      "apiName": "customEvent:achievement_id",
      "uiName": "Achievement ID",
      "description": "An event scoped custom dimension for your Analytics property."
    },
...
],

步驟 3：在報表要求中加入自訂維度。以下是傳送至 runReport 方法的範例要求。

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
  "dimensions": [{ "name": "customEvent:achievement_id" }],
  "metrics": [{ "name": "eventCount" }]
}

以使用者為範圍的自訂維度

步驟 1：使用資源 ID 查詢中繼資料 API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata

步驟 2：從回應中找出您想要製作報表，而您想要以使用者為範圍的自訂維度。如果沒有維度，則必須登錄維度。

"dimensions": [
...
    {
      "apiName": "customUser:last_level",
      "uiName": "Last level",
      "description": "A user property for your Analytics property."
    },
...
],

步驟 3：在報表要求中加入自訂維度。以下是傳送至 runReport 方法的範例要求。

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "entity": { "propertyId": "GA4_PROPERTY_ID" },
  "dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "customUser:last_level" }],
  "metrics": [{ "name": "activeUsers" }]
}

以事件為範圍的自訂指標

步驟 1：使用資源 ID 查詢中繼資料 API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata

步驟 2：找出您想從回應中建立報表的事件範圍自訂指標。如果沒有指標，則必須註冊指標。

"metrics": [
...
    {
      "apiName": "customEvent:credits_spent",
      "uiName": "Credits Spent",
      "description": "An event scoped custom metric for your Analytics property.",
      "type": "TYPE_STANDARD"
    },
...
],

步驟 3：在報表要求中加入自訂指標。以下是傳送至 runReport 方法的範例要求。

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "customEvent:credits_spent" }]
}

單次轉換的轉換率指標

步驟 1：使用資源 ID 查詢中繼資料 API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata

步驟 2：找出您想根據回應製作報表的轉換率指標。如果沒有轉換事件，則必須設定轉換事件。

"metrics": [
...
    {
      "apiName": "sessionConversionRate:add_to_cart",
      "uiName": "Session conversion rate for add_to_cart",
      "description": "The percentage of sessions in which a specific conversion event was triggered",
    },
...
],

步驟 3：在報表要求中加入轉換率指標。以下是傳送至 runReport 方法的範例要求。

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "sessionConversionRate:add_to_cart" }]
}

以事件為範圍的自訂指標平均值

步驟 1：使用資源 ID 查詢中繼資料 API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata

步驟 2：找出您想透過回應製作報表的「事件範圍自訂指標」平均值。如果沒有指標，則必須註冊指標。

"metrics": [
...
    {
      "apiName": "averageCustomEvent:credits_spent",
      "uiName": "Average Credits Spent",
      "description": "The average of an event scoped custom metric for your Analytics property.",
      "type": "TYPE_STANDARD"
    },
...
],

步驟 3：在報表要求中加入自訂指標平均值。以下是傳送至 runReport 方法的範例要求。

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}

同類群組報表範例

「同類群組」報表會為同類群組建立使用者留存時間序列。如需每個 API 欄位的詳細說明文件，請參閱 CohortSpec 的 REST 參考資料。

建立同類群組報表

以下提供同類群組報表範例，其中：

同類群組是 firstSessionDate 為 2020-12-01 的使用者；這項設定是透過 cohorts 物件進行設定。報表回應中的維度和指標只會以同類群組的使用者為依據。
同類群組報表會顯示三欄；這項設定是由維度和指標物件設定。
- 「cohort」維度是同類群組的名稱。
- 維度 cohortNthDay 是自 2020-12-01起的天數。
- 「cohortActiveUsers」指標是仍活躍的使用者人數。
cohortsRange 物件會指定報表應包含自 2020-12-01 開始，且這個同類群組的結尾為 2020-12-06 的事件資料。
- 如果使用 DAILY 的精細程度，建議使用 cohortNthDay 維度以維持一致性。

同類群組的報表要求如下：

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dimensions": [{ "name": "cohort" }, { "name": "cohortNthDay" }],
  "metrics": [{ "name": "cohortActiveUsers" }],
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-12-01", "endDate": "2020-12-01" }
      }
    ],
    "cohortsRange": {
      "endOffset": 5,
      "granularity": "DAILY"
    }
  },
}

針對這項要求，報表回應範例如下：

{
  "dimensionHeaders": [
    { "name": "cohort" }, { "name": "cohortNthDay" }
  ],
  "metricHeaders": [
    { "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
      "metricValues": [{ "value": "293" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
      "metricValues": [{ "value": "143" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
      "metricValues": [{ "value": "123" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
      "metricValues": [{ "value": "92" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0005" }],
      "metricValues": [{ "value": "86" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
      "metricValues": [{ "value": "83" }]
    }
  ],
  "metadata": {},
  "rowCount": 6
}

這份報表回覆之後，這份同類群組報表圖表即為一例。這份報表提供深入分析資訊，顯示這個同類群組中第一天和第二天之間的活躍使用者降幅最大。

以視覺化方式呈現同類群組使用者在特定期間的變化

多個同類群組和使用者留存率

獲取新客和留存率是拓展網站或應用程式的方法。同類群組報表著重於使用者留存率。在此範例中，報表顯示這項資源在兩週內，將 4 天的使用者留存率提高 10%。

建立這份報表時，請指定三個同類群組：第一個 firstSessionDate 為 2020-11-02，第二個為 2020-11-09，第二個則設為 2020-11-16。firstSessionDatefirstSessionDate由於這三天的資源使用者人數不同，因此我們會比較同類群組的使用者留存率 (cohortActiveUsers/cohortTotalUsers) 指標，而不是直接使用 cohortActiveUsers 指標。

這些同類群組的報表要求如下：

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dimensions": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
  "metrics": [
    {
      "name": "cohortRetentionFraction",
      "expression": "cohortActiveUsers/cohortTotalUsers"
    }
  ],
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-02", "endDate": "2020-11-02" }
      },
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-09", "endDate": "2020-11-09" }
      },
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-16", "endDate": "2020-11-16" }
      }
    ],
    "cohortsRange": {
      "endOffset": 4,
      "granularity": "DAILY"
    }
  },
}

針對這項要求，報表回應範例如下：

{
  "dimensionHeaders": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
  "metricHeaders": [{
      "name": "cohortRetentionFraction",
      "type": "TYPE_FLOAT"
    }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.308" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.272" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.257" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.248" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.235" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.211" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.198" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.172" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.167" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.155" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.141" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.118" }]
    }
  ],
  "metadata": {},
  "rowCount": 15
}

這份報表回覆之後，這份同類群組報表圖表即為一例。根據這份報告中，4 天內的使用者留存率在兩週內增加了 10%。firstSessionDate 為 2020-11-16 的較新同類群組超過了 firstSessionDate 為 2020-11-02 的較早同類群組。

多個同類群組回訪率圖表

每週同類群組以及搭配其他 API 功能使用同類群組

如要移除使用者行為的每日變化趨勢，請使用每週同類群組。在每週同類群組報表中，凡是在同一週具有 firstSessionDate 的使用者，都會形成同類群組。每週以星期日開始，星期六結束。此外，在這份報表中，我們也會建立同類群組的資料，比較俄羅斯境內使用者與活動在墨西哥的使用者。此切片使用 country 維度和 dimensionFilter 只會將這兩個國家/地區納入考量。

這些同類群組的報表要求如下：

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
  "dimensions": [
    { "name": "cohort" },
    { "name": "cohortNthWeek" },
    { "name": "country" }
  ],
  "metrics": [{ "name": "cohortActiveUsers" }],
  "dimensionFilter": {
    "filter": {
      "fieldName": "country",
      "inListFilter": {
        "values": [ "Russia", "Mexico" ]
      }
    }
  },
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": {
          "startDate": "2020-10-04",
          "endDate": "2020-10-10"
        }
      }
    ],
    "cohortsRange": {
      "endOffset": 5,
      "granularity": "WEEKLY"
    }
  },
}

針對這項要求，報表回應範例如下：

{
  "dimensionHeaders": [
    { "name": "cohort" },
    { "name": "cohortNthWeek" },
    { "name": "country" }
  ],
  "metricHeaders": [
    { "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0000" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "105" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0000" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "98" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0001" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "35" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0002" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "24" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0001" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "23" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0004" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "17" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0003" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "15" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0005" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "15" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0002" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "3" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0003" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0004" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "1" }]
    }
  ],
  "metadata": {},
  "rowCount": 11
}

下方是這份同類群組報表圖表。根據這份報表，相較於在俄羅斯境內有活動的使用者，這項資源在墨西哥境內有活動的使用者獲得更好的留存率。

國家/地區比較同類群組圖表