高级用例

本文档说明了 Google Analytics(分析)Reporting API v4 的高级功能。有关这一 API 的详细参考,请参阅参考指南

简介

创建简单的报告之后,请使用这些功能来创建高级报告:

数据透视

可使用 Google Analytics(分析)Reporting API v4 生成数据透视表。要使用数据透视表构建请求,请在 ReportRequest 中定义 Pivot 字段。Pivot 对象有自己的一组维度、指标和可选的 startGroupmaxGroupCount,可指定要包含在数据透视表中的维度数。

请求

下面的 API 调用按国家/地区请求会话,并在浏览器上对结果进行数据透视:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges":
      [
        {
          "startDate": "2014-11-01",
          "endDate": "2014-11-30"
        }
      ],
      "metrics":
      [
        {
          "expression": "ga:sessions"
        }
      ],
      "dimensions":
      [
        {
          "name": "ga:country"
        }
      ],
      "pivots":
      [
        {
          "dimensions":
          [
            {
              "name": "ga:browser"
            }
          ],
          "maxGroupCount": 3,
          "startGroup": 3,
          "metrics":
          [
            {
              "expression": "ga:sessions"
            }
          ]
        }
      ]
    }
  ]
}

响应列标题

在为数据透视请求返回的报告对象中,metricHeader 有一列 pivotHeaders 对象,其 pivotHeaderEntries 字段定义数据透视维度值以及相应指标值的顺序,例如:

"columnHeader": {
    "dimensions": [
        "ga:country"
    ],
    "metricHeader": {
        "metricHeaderEntries": [
            {
                "name": "ga:sessions",
                "type": "INTEGER"
            }
        ],
        "pivotHeaders": [
            {
                "pivotHeaderEntries": [
                    {
                        "dimensionNames": [
                            "ga:browser"
                        ],
                        "dimensionValues": [
                            "Internet Explorer"
                        ],
                        "metric": {
                            "name": "ga:sessions",
                            "type": "INTEGER"
                        }
                    },
                    {
                        "dimensionNames": [
                            "ga:browser"
                        ],
                        "dimensionValues": [
                            "Firefox"
                        ],
                        "metric": {
                            "name": "ga:sessions",
                            "type": "INTEGER"
                        }
                    },
                    {
                        "dimensionNames": [
                            "ga:browser"
                        ],
                        "dimensionValues": [
                            "Android Browser"
                        ],
                        "metric": {
                            "name": "ga:sessions",
                            "type": "INTEGER"
                        }
                    }
                ],
                "totalPivotGroupsCount": 7
            }
        ]
    }
},

响应行

reportData 对象的每一行定义了一组 dateRangeValue 对象,其中每个又包含一组 pivotValue 对象;值的顺序对应于响应列标题里数据透视标题中列出的指标顺序。

"rows": [
    ...
    {
        "dimensions": [
            "United States"
        ],
        "metrics": [
            {
                "pivotValues": [
                    {
                        "values": [
                            "21",
                            "18",
                            "1"
                        ]
                    }
                ],
                "values": [
                    "192"
                ]
            }
        ]
    }
],

请注意,报告中只有三个数据透视值,原因是在原始的请求中,maxGroupCount 是 3。因为 "totalPivotGroupsCount": 7,最多可以有七个值。

数据透视表行示例

在上面的示例响应中,与国家/地区美国相关的行在以下数据透视表中表示为:

国家/地区 总计
会话
Internet Explorer
会话
Firefox
会话
Android 浏览器
会话
印度 12 3 2 4
美国 192 21 18 1
英国 35 12 2 0

同类群组

同类群组是具有共同特征的一组用户。例如,流量获取日期相同的所有用户属于同一个同类群组。同类群组分析报告能帮助您分离和分析同类群组行为。有关同类群组所特有的一列维度和指标,请参阅同类群组和生命周期价值维度和指标

要定义同类群组请求,您必须使用 nametypedateRange 定义 cohort 对象:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions":
      [
        {
          "name": "ga:cohort"
        },
        {
          "name": "ga:cohortNthDay"
        }
      ],
      "metrics":
      [
        {
          "expression": "ga:cohortActiveUsers"
        },
        {
          "expression": "ga:cohortTotalUsers"
        }
      ],
      "cohortGroup":
      {
        "cohorts":
        [
          {
            "name": "cohort 1",
            "type": "FIRST_VISIT_DATE",
            "dateRange":
            {
              "startDate": "2015-08-01",
              "endDate": "2015-08-01"
            }
          },
          {
            "name": "cohort 2",
            "type": "FIRST_VISIT_DATE",
            "dateRange":
            {
              "startDate": "2015-07-01",
              "endDate": "2015-07-01"
            }
          }
        ]
      }
    }
  ]
}

API Explorer 中查看上例。

同类群组限制

有效的同类群组请求必须满足以下限制条件:

  • 当且仅当请求中包含一个或多个同类群组定义时,才加入 ga:cohort 维度。
  • 同类群组名称必须是唯一的。
  • 一个请求中的同类群组数目上限是 12 个。
  • 如果定义了 ga:cohortNthWeek,则应以星期日为开始日期,以星期六为结束日期。如果定义了 ga:cohortNthMonth,则应以月的第一天为开始日期,以该月的最后一天为结束日期。如果定义了 ga:cohortNthDay,则日期范围必须刚好是一天。
  • 同类群组请求不允许使用当天的日期。
  • 同类群组和非同类群组请求不应位于同一 batchGet 请求中。
  • 同类群组中的日期范围必须在 2015 年 2 月 1 日之后。

生命周期价值

生命周期价值报告会向您显示在赢得用户之后的 90 天内,用户价值(收入)和互动(应用浏览次数、目标达成次数、会话次数和会话时长)的增长情况。请参阅生命周期价值所特有的维度和指标

根据定义,生命周期价值请求是将 lifetimeValue 字段设为 true同类群组,例如:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions":
      [
        {
          "name": "ga:cohort"
        },
        {
          "name": "ga:cohortNthWeek"
        }
      ],
      "metrics":
      [
        {
          "expression": "ga:cohortTotalUsersWithLifetimeCriteria"
        },
        {
          "expression": "ga:cohortRevenuePerUser"
        }
      ],
      "cohortGroup":
      {
        "cohorts":
        [
          {
            "name": "cohort 1",
            "type": "FIRST_VISIT_DATE",
            "dateRange":
            {
              "startDate": "2015-08-01",
              "endDate": "2015-09-01"
            }
          },
          {
            "name": "cohort 2",
            "type": "FIRST_VISIT_DATE",
            "dateRange":
            {
              "startDate": "2015-07-01",
              "endDate": "2015-08-01"
            }
          }
        ],
        "lifetimeValue": true
      }
    }
  ]
}

API Explorer 中查看上例。

同类群组和生命周期价值维度和指标

维度

维度名称 定义
ga:cohort 用户所属的同类群组名称。与一位用户可以属于多个细分类似,取决于同类群组的定义方式,一位用户可以属于多个同类群组。
ga:cohortNthDay 相对于同类群组定义日期,以 0 为起点的日期偏移。例如,如果将同类群组的首次访问日期定义为 2015-09-01,那么对于 2015-09-04ga:cohortNthDay 将是 3。
ga:cohortNthMonth 相对于同类群组定义日期,以 0 为起点的月份偏移。
ga:cohortNthWeek 相对于同类群组定义日期,以 0 为起点的周偏移。
ga:acquisitionTrafficChannel 赢得用户的流量渠道,提取自用户的第一个会话。在赢得用户之时,基于默认的渠道分组规则计算流量渠道(如果在数据视图级别有的话)。
ga:acquisitionSource 赢得用户的来源,来自于用户的第一个会话。
ga:acquisitionMedium 赢得用户的媒介,来自于用户的第一个会话。
ga:acquisitionSourceMedium ga:userAcquisitionSourcega:acquisitionMedium 的合并值。
ga:acquisitionCampaign 赢得用户的广告系列,来自于用户的第一个会话。

指标

指标名称 定义
ga:cohortActiveUsers 此指标适用于偏移维度(ga:cohortNthDayga:cohortNthWeekga:cohortNthMonth)以 0 为起点的情况。它表明在与同类群组第 N 个时间段(天、周、月)相对应的时间窗口中活动的同类群组中的用户数。例如,对于 ga:cohortNthWeek = 1,是在第二周活动的(同类群组中的)用户数。如果请求没有任何的 ga:cohortNthDayga:cohortNthWeekga:cohortNthMonth,此指标将与 ga:cohortTotalUsers 有相同的值。
ga:cohortTotalUsers 属于同类群组的用户数,也称为同类群组规模。
ga:cohortAppviewsPerUser 同类群组中每用户的应用浏览次数。
ga:cohortGoalCompletionsPerUser 同类群组中每用户的目标达成次数。
ga:cohortPageviewsPerUser 同类群组中每用户的网页浏览次数。
ga:cohortRetentionRate 同类群组留存率。
ga:cohortRevenuePerUser 同类群组中每用户的收入。
ga:cohortVisitDurationPerUser 同类群组中每用户的会话时长。
ga:cohortSessionsPerUser 同类群组中每用户的会话次数。

生命周期价值指标

指标名称 定义
ga:cohortTotalUsersWithLifetimeCriteria 此指标适用于请求具有 ga:acquisitionTrafficChannelga:acquisitionSourcega:acquisitionMediumga:acquisitionCampaign 维度的情况。它代表通过当前渠道、来源、媒介或广告系列赢得的同类群组中用户的数量。例如,ga:acquisitionTrafficChannel=Direct 代表直接赢得的同类群组中用户的数量。如果上述维度都不存在,则其值等于 ga:cohortTotalUsers(仅限应用浏览)。
ga:cohortAppviewsPerUserWithLifetimeCriteria 同类群组中流量获取维度每用户的应用浏览次数(仅限应用浏览)。
ga:cohortGoalCompletionsPerUserWithLifetimeCriteria 同类群组中流量获取维度每用户的目标达成次数(仅限应用浏览)。
ga:cohortPageviewsPerUserWithLifetimeCriteria 同类群组中流量获取维度每用户的网页浏览次数(仅限应用浏览)。
ga:cohortRevenuePerUserWithLifetimeCriteria 同类群组中流量获取维度每用户的收入(仅限应用浏览)。
ga:cohortSessionsPerUserWithLifetimeCriteria 同类群组中流量获取维度每用户的会话时长(仅限应用浏览)。