User Activity API 可讓 Google Analytics (分析) 資源擁有者擷取與單一使用者相關的「所有」數據分析評估資料。具體來說,API 會擷取與特定使用者 ID 或用戶端 ID 相關聯的所有評估資料。
提出使用者活動要求
如要提出使用者活動要求,請使用下列欄位建構要求物件:
與使用者相關聯的 Client-ID 或 User-ID
- 如要進一步瞭解如何查詢這些欄位,請參閱「Cookie 和使用者識別資訊」一文。
Analytics (分析) 資料檢視 ID,內含與使用者相關聯的資料。
- 您可以使用 Account Explorer 查詢資料檢視 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 傳回的資料是階層結構的,因此開發人員需要特別注意一些事項,才能正確整理資料。
分頁的基本「列」類型為「活動」。由於使用者資料是按工作階段分組,因此網頁界線可能會在工作階段內發生,而該工作階段可能包含橫跨多個頁面的活動。
範例資料
為進行示範,我們將使用下列範例資料。在本例中,使用者在 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 |
單頁
如果您以至少 18 的 pageSize
提出使用者活動要求,資料將會在單一頁面中傳送,看起來會像這樣:
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
欄位會顯示傳回的使用者活動比例。
資料取樣方式
使用者資料是在活動層級進行取樣。舉例來說,如果取樣率為 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