高级用例

本文档介绍了 Google Analytics 的一些高级功能 Data API v1。 有关该 API 的详细参考信息，请参阅 API 参考。

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

Data API 可以针对已注册的自定义 维度和自定义 指标。Metadata API 方法可用于列出该 API。 名称。这些 API 名称可以是 用于向 runReport 方法。

以下部分展示了每种自定义设置的示例。在 请将 GA_PROPERTY_ID 替换为您的媒体资源 ID。

事件级范围的自定义维度

第 1 步：查询 Metadata API Method 替换为您的媒体资源 ID。

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 步：查询 Metadata API Method 替换为您的媒体资源 ID。

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 步：查询 Metadata API Method 替换为您的媒体资源 ID。

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 步：查询 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 步：查询 Metadata API Method 替换为您的媒体资源 ID。

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。

创建同类群组报告

以下是同类群组报告的示例，其中：

  • 同类群组是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 天用户留存率在 2023 年 为期两周的课程较晚的同类群组（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 字段。Google Data API 的比较功能与此类似， 了解 Google Analytics 前端中的比较功能。

有关每个 API 字段的详细文档，请参阅 比较。

创建比较项

您可以为要比较的每个数据集创建单独的比较项。 例如，要比较应用和网站数据，您可以为 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"
        }
      ]
    },

    ...

  ],

...

}