User Activity API

User Activity API 可讓 Google Analytics (分析) 資源擁有者擷取與單一使用者相關的「所有」數據分析評估資料。具體來說，API 會擷取與特定使用者 ID 或用戶端 ID 相關聯的所有評估資料。

注意： 請參閱 User-ID 參考資料概略瞭解用戶端 ID、User ID 及其差異。

提出使用者活動要求

如要提出使用者活動要求，請使用下列欄位建構要求物件：

1. 與使用者相關聯的 Client-ID 或 User-ID

   • 如要進一步瞭解如何查詢這些欄位，請參閱「Cookie 和使用者識別資訊」一文。

2. Analytics (分析) 資料檢視 ID，內含與使用者相關聯的資料。

   • 您可以使用 Account Explorer 查詢資料檢視 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 (分析) 中的工作階段定義方式，請參閱「Analytics (分析) 中的網頁工作階段定義方式」一文

注意： Activity 參考資料包含更精準的活動定義，還有一些細微方式與命中或事件的差別。

分頁

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

注意： 由於可能的隨機資料分群法，這些子範圍也可能經過取樣。舉例來說，如果使用者的大部分資料是在 2018-01-01 到 2018-03-31 這個日期範圍內，就可能需要執行其他要求，直到擁有所有未取樣資料為止。