高级用例

本文档介绍了 Google Analytics Data API v1 的多项高级功能。如需查看该 API 的详细参考文档，请参阅 API 参考文档。

列出自定义定义并创建报告

Data API 可以根据已注册的自定义维度和自定义指标创建报告。Metadata API 方法可用于列出媒体资源已注册的自定义定义的 API 名称。例如，这些 API 名称可用于向 runReport 方法发出的报告请求中。

以下部分展示了每种类型的自定义定义的示例。在这些示例中，请将 GA_PROPERTY_ID 替换为您的媒体资源 ID。

事件级范围的自定义维度

第 1 步：使用媒体资源 ID 查询 Metadata API Method。

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 Method。

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 Method。

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 Method。

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 字段，请参阅 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/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%。2020-11-16 firstSessionDate 较高的后期同类群组的留存率高于 2020-11-02 firstSessionDate 较低的前期同类群组。

多个同类群组留存率图表

每周同类群组以及将同类群组与其他 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 来匹配值为“iOS”和“Android”的 platform 维度。第二个比较项（名为“网站流量”）使用 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"         }       ]     },      ...    ],  ...  }