借助 User Activity API,Google Analytics(分析)媒体资源所有者可以检索与单个用户关联的所有分析衡量数据。具体而言,该 API 会检索与特定用户 ID 或客户端 ID 关联的所有衡量数据。
发出用户活动请求
如需发出用户活动请求,请使用以下字段构建一个请求对象:
与用户关联的 Client-ID 或 User-ID
- 如需详细了解如何查询这些字段,请参阅 Cookie 和用户识别。
包含与用户相关联的数据的 Google Analytics(分析)数据视图 ID。
- 您可以使用帐号浏览器查找数据视图 ID。
虽然并非必需,但您可能需要为您感兴趣的数据指定日期范围。默认情况下,该 API 会列出过去一周的用户活动。
示例请求
POST https://analyticsreporting.googleapis.com/v4/userActivity:search
{
"viewId": "9999999",
"user": {
"type": "CLIENT_ID",
"userId": "1034600000.76425000000"
},
"dateRange": {
"startDate": "2018-01-01",
"endDate": "2018-12-31",
}
}
示例响应
{
"sessions": [{
"sessionId": "1539184430",
"deviceCategory": "desktop",
"platform": "Windows",
"dataSource": "web",
"sessionDate": "2018-10-10"
"activities": [{
"activityTime": "2018-10-10T08:13:50.555105Z",
"source": "(direct)",
"medium": "(none)",
"channelGrouping": "Direct",
"campaign": "(not set)",
"keyword": "(not set)",
"hostname": "shop.googlemerchandisestore.com",
"landingPagePath": "/gpsmap",
"activityType": "PAGEVIEW",
"customDimension": [{
"index": 1,
"value": "(not set)"
}, ...]
}, ...]
}, ...]
"totalRows": 1000,
"nextPageToken": "A6JGY3",
"sampleRate": 1
}
课程与活动
用户活动数据按会话分组。每个会话都包含有关会话的一般信息(例如会话 ID 和日期)以及该会话的用户活动列表。会话中的用户活动包含用户负责的每次“命中”,其中包括网页浏览、电子商务事件以及通过 gtag(...)
或 ga(...)
发送的自定义事件等。
分页
User Activity API 使用分页功能将大型数据集分解为多个请求和响应。但是,由于该 API 返回的数据以分层方式整理,因此开发者需要采取一些特殊注意事项来正确整理数据。
用于分页的基本“行”类型是 Activity。由于用户数据是按会话分组的,这意味着会话内部可能会出现页面边界,并且该会话可以有跨多个页面的活动。
示例数据
出于演示目的,我们将使用以下示例数据。在此示例中,用户在 3 天内在 6 个会话中与网站进行了互动。
日期 | 会话 ID | 事件标签 | 时间 |
---|---|---|---|
2018-11-23 | 1 | A | 10:26 |
2018-11-23 | 1 | B | 10:32 |
2018-11-23 | 1 | C | 10:39 |
2018-11-23 | 2 | A | 18:04 |
2018-11-23 | 2 | B | 18:11 |
2018-11-23 | 2 | C | 18:26 |
2018-11-24 | 3 | A | 11:26 |
2018-11-24 | 3 | B | 11:29 |
2018-11-24 | 3 | C | 11:39 |
2018-11-24 | 3 | D | 11:42 |
2018-11-24 | 4 | A | 23:50 |
2018-11-24 | 4 | B | 23:54 |
2018-11-25 | 5 | C | 00:02 |
2018-11-25 | 5 | D | 00:13 |
2018-11-25 | 6 | A | 13:01 |
2018-11-25 | 6 | B | 13:09 |
2018-11-25 | 6 | C | 13:12 |
2018-11-25 | 6 | D | 13:23 |
单页
如果您发出 pageSize
至少为 18 的用户活动请求,则所有数据都将在单个页面中传送,并且如下所示:
POST https://analyticsreporting.googleapis.com/v4/userActivity:search
{
"viewId": "9999999",
"user": {
"type": "CLIENT_ID",
"userId": "1034600000.76425000000",
},
"dateRange": {
"startDate": "2018-11-20",
"endDate": "2018-11-30",
},
"pageSize": 100,
}
{
"totalRows": 18,
"sessions": [{
"sessionId": "1",
"sessionDate": "2018-11-23",
"activities": [{
"activityTime": "2018-11-23T10:26:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-23T10:32:00",
"event": {"eventLabel": "B"}
}, {
"activityTime": "2018-11-23T10:39:00",
"event": {"eventLabel": "C"}
}]
}, {
"sessionId": "2",
"sessionDate": "2018-11-23",
"activities": [{
"activityTime": "2018-11-23T18:04:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-23T18:11:00",
"event": {"eventLabel": "B"}
}, {
"activityTime": "2018-11-23T18:26:00",
"event": {"eventLabel": "C"}
}]
}, {
"sessionId": "3",
"sessionDate": "2018-11-24",
"activities": [{
"activityTime": "2018-11-24T11:26:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-24T11:29:00",
"event": {"eventLabel": "B"}
}, {
"activityTime": "2018-11-24T11:39:00",
"event": {"eventLabel": "C"}
}, {
"activityTime": "2018-11-24T11:42:00",
"event": {"eventLabel": "D"}
}]
}, {
"sessionId": "4",
"sessionDate": "2018-11-24",
"activities": [{
"activityTime": "2018-11-24T23:50:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-24T23:54:00",
"event": {"eventLabel": "B"}
}]
}, {
"sessionId": "5",
"sessionDate": "2018-11-25",
"activities": [{
"activityTime": "2018-11-25T00:01:00",
"event": {"eventLabel": "C"}
}, {
"activityTime": "2018-11-25T00:13:00",
"event": {"eventLabel": "D"}
}]
}, {
"sessionId": "6",
"sessionDate": "2018-11-25",
"activities": [{
"activityTime": "2018-11-25T13:01:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-25T13:09:00",
"event": {"eventLabel": "B"}
}, {
"activityTime": "2018-11-25T10:12:00",
"event": {"eventLabel": "C"}
}, {
"activityTime": "2018-11-25T10:23:00",
"event": {"eventLabel": "D"}
}]
}]
}
多页面
但是,如果您的页面大小为 5,则这些数据将分为 4 个响应页面:
日期 | 会话 ID | 事件标签 | 时间 |
---|---|---|---|
第 1 页: | |||
2018-11-23 | 1 | A | 10:26 |
2018-11-23 | 1 | B | 10:32 |
2018-11-23 | 1 | C | 10:39 |
2018-11-23 | 2 | A | 18:04 |
2018-11-23 | 2 | B | 18:11 |
第 2 页: | |||
2018-11-23 | 2 | C | 18:26 |
2018-11-24 | 3 | A | 11:26 |
2018-11-24 | 3 | B | 11:29 |
2018-11-24 | 3 | C | 11:39 |
2018-11-24 | 3 | D | 11:42 |
第 3 页: | |||
2018-11-24 | 4 | A | 23:50 |
2018-11-24 | 4 | B | 23:54 |
2018-11-25 | 5 | C | 00:02 |
2018-11-25 | 5 | D | 00:13 |
2018-11-25 | 6 | A | 13:01 |
第 4 页: | |||
2018-11-25 | 6 | B | 13:09 |
2018-11-25 | 6 | C | 13:12 |
2018-11-25 | 6 | D | 13:23 |
请注意,会话 2 分为第一页和第二页,11 月 24 日的 2 次会话分为第二页和第三页。 响应将如下所示:
{
"totalRows": 18,
"nextPageToken": "UGMGQS",
"sessions": [{
"sessionId": "1",
"sessionDate": "2018-11-23",
"activities": [{
"activityTime": "2018-11-23T10:26:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-23T10:32:00",
"event": {"eventLabel": "B"}
}, {
"activityTime": "2018-11-23T10:39:00",
"event": {"eventLabel": "C"}
}]
}, {
"sessionId": "2",
"sessionDate": "2018-11-23",
"activities": [{
"activityTime": "2018-11-23T18:04:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-23T18:11:00",
"event": {"eventLabel": "B"}
}]
}]
}
{
"totalRows": 18,
"nextPageToken": "1FKOME",
"sessions": [{
"sessionId": "2",
"sessionDate": "2018-11-23",
"activities": [{
"activityTime": "2018-11-23T18:26:00",
"event": {"eventLabel": "C"}
}]
}, {
"sessionId": "3",
"sessionDate": "2018-11-24",
"activities": [{
"activityTime": "2018-11-24T11:26:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-24T11:29:00",
"event": {"eventLabel": "B"}
}, {
"activityTime": "2018-11-24T11:39:00",
"event": {"eventLabel": "C"}
}, {
"activityTime": "2018-11-24T11:42:00",
"event": {"eventLabel": "D"}
}]
}]
}
{
"totalRows": 18,
"nextPageToken": "7S77H6",
"sessions": [{
"sessionId": "4",
"sessionDate": "2018-11-24",
"activities": [{
"activityTime": "2018-11-24T23:50:00",
"event": {"eventLabel": "A"}
}, {
"activityTime": "2018-11-24T23:54:00",
"event": {"eventLabel": "B"}
}]
}, {
"sessionId": "5",
"sessionDate": "2018-11-25",
"activities": [{
"activityTime": "2018-11-25T00:01:00",
"event": {"eventLabel": "C"}
}, {
"activityTime": "2018-11-25T00:13:00",
"event": {"eventLabel": "D"}
}]
}, {
"sessionId": "6",
"sessionDate": "2018-11-25",
"activities": [{
"activityTime": "2018-11-25T13:01:00",
"event": {"eventLabel": "A"}
}]
}]
}
{
"totalRows": 18,
"sessions": [{
"sessionId": "6",
"sessionDate": "2018-11-25",
"activities": [{
"activityTime": "2018-11-25T13:09:00",
"event": {"eventLabel": "B"}
}, {
"activityTime": "2018-11-25T10:12:00",
"event": {"eventLabel": "C"}
}, {
"activityTime": "2018-11-25T10:23:00",
"event": {"eventLabel": "D"}
}]
}]
}
数据抽样
如果客户端在请求的日期范围积累了大量数据,则 API 可能仅返回抽样的活动子集。在这种情况下,sampleRate
字段会指明返回的用户 activity 的比例。
如何对数据进行抽样
用户数据在活动级别进行抽样。例如,如果采样率为 50% (0.5
),则有一半用户活动出现在响应中。
这些采样活动是随机选择的;该 API 不对随机采样提供任何保证,也不保证这些采样在给定日期范围内与不同活动成比例。
防止数据抽样
由于此 API 将会话视为活动的集合,因此采样集中没有出现任何活动的会话将不会出现在响应中。如果您需要会话或活动的完整列表,请发送范围较小的后续请求。
例如,如果您请求从 2018-01-01
到 2018-12-31
的数据,并且响应指示采样率为 0.25
,请将请求的日期范围分为 4 部分,使每个部分应包含大约四分之一的原始数据:
2018-01-01
-2018-03-31
2018-04-01
至2018-06-30
2018-07-01
至2018-09-30
2018-10-01
-2018-12-31