User Activity API

借助 User Activity API，Google Analytics（分析）媒体资源所有者可以检索与单个用户关联的所有分析衡量数据。具体而言，该 API 会检索与特定用户 ID 或客户端 ID 关联的所有衡量数据。

注意 ：请参阅 User-ID 参考文档，简要了解客户端 ID、User ID 以及它们之间的差异。

发出用户活动请求

如需发出用户活动请求，请使用以下字段构建一个请求对象：

1. 与用户关联的 Client-ID 或 User-ID

   • 如需详细了解如何查询这些字段，请参阅 Cookie 和用户识别。

2. 包含与用户相关联的数据的 Google Analytics（分析）数据视图 ID。

   • 您可以使用帐号浏览器查找数据视图 ID。

3. 虽然并非必需，但您可能需要为您感兴趣的数据指定日期范围。默认情况下，该 API 会列出过去一周的用户活动。

注意 ：如需查看此 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(...) 发送的自定义事件等。

注意 ：会话不能跨越日期边界。如果用户在网站上停留的时间分为两个不同的日期，则会显示为不同日期的两个不同的会话。如需详细了解如何在 Google Analytics（分析）中定义会话，请参阅 Google Analytics（分析）中如何定义网络会话

注意： Activity 参考文档包含对 Activity 的更精确定义，以及与命中或事件不同的细微差别。

分页

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

注意 ：用户 activity 始终按一定顺序排列，这意味着页面之间的边界绝不会是随机的，而是始终位于时间相邻的会话与 activity 之间。

请注意，会话 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

注意 ：由于可能的随机数据聚类，这些子范围也可能被采样。例如，如果用户的大部分数据都发生在 2018-01-01 到 2018-03-31 的日期范围内，您可能需要执行其他请求，直到获得所有未抽样数据为止。