試用 Google Analytics 的 MCP 伺服器。從 GitHub 安裝，詳情請參閱公告。

進階用途

本文說明 Google Analytics Data API v1 的幾項進階功能。如需 API 的詳細參考資料，請參閱「API 參考資料」。

列出自訂定義並建立報表

Data API 可根據已註冊的自訂維度和自訂指標建立報表。您可以使用中繼資料 API 方法，列出資源已註冊自訂定義的 API 名稱。這些 API 名稱可用於報表要求，例如 runReport 方法。

下列各節會顯示每種自訂定義的範例。在這些範例中，請將 GA_PROPERTY_ID 替換為您的資源 ID。

以事件為範圍的自訂維度

步驟 1：使用資源 ID 查詢 Metadata API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_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/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
  "dimensions": [{ "name": "customEvent:achievement_id" }],
  "metrics": [{ "name": "eventCount" }]
}

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

步驟 1：使用資源 ID 查詢 Metadata API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_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/GA_PROPERTY_ID:runReport
{
  "entity": { "propertyId": "GA_PROPERTY_ID" },
  "dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "customUser:last_level" }],
  "metrics": [{ "name": "activeUsers" }]
}

事件界定範圍自訂指標

步驟 1：使用資源 ID 查詢 Metadata API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_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/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "customEvent:credits_spent" }]
}

單一重要事件的重要事件發生率指標

步驟 1：使用資源 ID 查詢 Metadata API 方法。

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

步驟 2：從回應中找出您感興趣並想建立報表的重要事件，然後取得該事件的重要事件發生率指標。如果沒有重要事件，請設定重要事件。

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

步驟 3：在報表要求中加入重要事件發生率指標。以下是向 runReport 方法提出的要求範例。

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

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

步驟 1：使用資源 ID 查詢 Metadata API 方法。

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_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/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}

同類群組報表範例

同類群組報表會建立同類群組的使用者留存率時間序列。如需各個 API 欄位的詳細說明文件，請參閱同類群組規格的 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/GA_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，第二個同類群組的 firstSessionDate 為 2020-11-09，第三個同類群組的 firstSessionDate 為 2020-11-16。由於這三天的資源使用者人數不同，我們會比較同類群組的cohortActiveUsers/cohortTotalUsers使用者留存率指標，而非直接使用cohortActiveUsers指標。

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

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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/GA_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
}

這份報表的回覆內容後面會附上同類群組報表的圖表。根據這份報表，與在俄羅斯有活動的使用者相比，這項資源在墨西哥有活動的使用者留存率較高。

國家/地區比較群組圖表

比較項目

您可以使用比較功能來對照評估不同的資料子集。您可以透過在報表定義中指定 comparisons 欄位來定義比較條件。Data API 的比較功能與 Google Analytics 前端的比較功能類似。

如需各個 API 欄位的詳細說明文件，請參閱比較的 REST 參考資料。

建立比較項目

您可以為每個要比較的資料集分別建立比較項目。舉例來說，如要比較應用程式與網站資料，您可以為 Android 和 iOS 資料建立一個比較項目，並為網站資料建立另一個比較項目。

以下是範例報表，其中定義了兩項比較，並傳回依國家/地區細分的活躍使用者。

名為「應用程式流量」的第一項比較會使用 inListFilter，比對 platform 維度與「iOS」和「Android」值。第二項名為「網站流量」的比較項目使用 stringFilter，將 platform 維度與「網站」相符。

  POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
  {
    "comparisons": [
      {
        "name": "App traffic",
        "dimensionFilter": {
          "filter": {
            "fieldName": "platform",
            "inListFilter": {
              "values": [
                "iOS",
                "Android"
              ]
            }
          }
        }
      },
      {
        "name": "Web traffic",
        "dimensionFilter": {
          "filter": {
            "fieldName": "platform",
            "stringFilter": {
              "matchType": "EXACT",
              "value": "web"
            }
          }
        }
      }
    ],
    "dateRanges": [
      {
        "startDate": "2024-05-01",
        "endDate": "2024-05-15"
      }
    ],
    "dimensions": [
      {
        "name": "country"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ]
  }

對於使用比較功能的所有要求，系統會自動在產生的報表中加入 comparison 欄位。這個欄位包含要求中提供的比較名稱。

以下是包含比較的範例回應程式碼片段：

{
  "dimensionHeaders": [
    {
      "name": "comparison"
    },
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [
    {
      "dimensionValues": [
        {
          "value": "Web traffic"
        },
        {
          "value": "United States"
        }
      ],
      "metricValues": [
        {
          "value": "638572"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Web traffic"
        },
        {
          "value": "Japan"
        }
      ],
      "metricValues": [
        {
          "value": "376578"
        }
      ]
    },
  {
      "dimensionValues": [
        {
          "value": "App traffic"
        },
        {
          "value": "United States"
        }
      ],
      "metricValues": [
        {
          "value": "79527"
        }
      ]
    },

    ...

  ],

...

}

進階用途 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

列出自訂定義並建立報表

以事件為範圍的自訂維度

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

事件界定範圍自訂指標

單一重要事件的重要事件發生率指標

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

同類群組報表範例

建立同類群組報表

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

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

比較項目

建立比較項目

進階用途