本文件說明 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": "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/GA4_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "sessionKeyEventRate: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
。firstSessionDate
firstSessionDate
由於這三天的資源使用者人數不同,因此我們會比較同類群組的使用者留存率 (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
}
下方是這份同類群組報表圖表。根據這份報表,相較於在俄羅斯境內有活動的使用者,這項資源在墨西哥境內有活動的使用者獲得更好的留存率。
比較項目
比較項目可用於對照評估不同的資料子集,您可以在報表定義中指定 comparisons
欄位,定義比較項目。Data API 的「比較」功能與 Google Analytics (分析) 前端的比較功能類似。
如需每個 API 欄位的詳細說明文件,請參閱比較的 REST 參考資料。
建立比較項目
您可以針對要比較的每個資料集建立獨立的比較項目。舉例來說,如要比較應用程式和網站資料,您可以為 Android 和 iOS 資料建立一項比較項目,並針對網站資料分別建立比較。
以下報表範例定義了兩項比較,並傳回按國家/地區細分的活躍使用者。
第一個名為「應用程式流量」的比較使用 inListFilter
,以比對 platform
維度與「iOS」和「Android」的值。第二個名為「網站流量」的比較會使用 stringFilter
,比對 platform
維度與「網站」。
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_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"
}
]
},
...
],
...
}