API hoạt động của người dùng

API hoạt động của người dùng cho phép chủ sở hữu tài sản Google Analytics truy xuất tất cả dữ liệu đo lường phân tích được liên kết với một người dùng. Cụ thể, API này truy xuất tất cả dữ liệu đo lường được liên kết với một User ID hoặc Client ID cụ thể.

Lưu ý: Hãy xem Tài liệu tham khảo về User-ID để biết thông tin giới thiệu ngắn gọn về Client-ID, User ID và sự khác biệt giữa chúng.

Tạo yêu cầu về hoạt động của người dùng

Để tạo Yêu cầu hoạt động của người dùng, hãy tạo đối tượng yêu cầu với các trường sau:

1. Client-ID hoặc User ID được liên kết với người dùng

   • Hãy xem phần Cookie và thông tin nhận dạng người dùng để biết thông tin chi tiết về cách tra cứu các trường này.

2. Mã chế độ xem Analytics chứa dữ liệu được liên kết với người dùng.

   • Bạn có thể sử dụng Trình khám phá tài khoản để tra cứu mã chế độ xem của mình.

3. Mặc dù không bắt buộc, nhưng có thể bạn sẽ cần một phạm vi ngày cho dữ liệu mà bạn quan tâm. Theo mặc định, API liệt kê hoạt động của người dùng trong tuần vừa qua.

Lưu ý: Hãy xem tài liệu tham khảo để biết danh sách đầy đủ các trường mà API này chấp nhận, bao gồm cả giá trị mặc định cho các trường không bắt buộc.

Yêu cầu mẫu

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",
    }
}

Phản hồi mẫu

{
    "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
}

Lưu ý: Trong ví dụ này, chúng ta sử dụng ... để biểu thị các mảng bị cắt bớt

Phiên hoạt động và hoạt động

Dữ liệu hoạt động của người dùng được nhóm theo phiên. Mỗi phiên chứa thông tin chung về phiên, chẳng hạn như mã phiên và ngày, cũng như danh sách hoạt động của người dùng cho phiên đó. Hoạt động của người dùng trong một phiên bao gồm mọi "lượt truy cập" mà người dùng chịu trách nhiệm; bao gồm các hoạt động như lượt xem trang, sự kiện thương mại điện tử và sự kiện tuỳ chỉnh được gửi qua gtag(...) hoặc ga(...).

Lưu ý: Phiên hoạt động không được kéo dài phạm vi ngày. Nếu thời gian của người dùng trên trang web của bạn kéo dài hai ngày khác nhau, thì thời gian này sẽ xuất hiện dưới dạng hai phiên khác nhau vào các ngày khác nhau. Để biết thêm thông tin về cách xác định một phiên trong Google Analytics, hãy xem phần Cách xác định một phiên trên web trong Analytics

Lưu ý: tài liệu tham khảo Activity chứa định nghĩa chính xác hơn về một Hoạt động và những điểm khác biệt tinh tế giữa phiên hoạt động với Lượt truy cập hoặc Sự kiện.

Phân trang

API hoạt động của người dùng sử dụng tính năng phân trang để chia các tập dữ liệu lớn thành nhiều yêu cầu và phản hồi. Tuy nhiên, vì dữ liệu mà API trả về có cấu trúc theo hệ phân cấp, nên nhà phát triển cần xem xét một số điểm đặc biệt để đối chiếu dữ liệu một cách chính xác.

Loại "hàng" cơ bản dùng để phân trang là Hoạt động. Vì Dữ liệu người dùng được nhóm theo phiên, nên điều này có nghĩa là ranh giới trang có thể xảy ra bên trong một phiên và phiên đó có thể có các hoạt động trên nhiều trang.

Lưu ý quan trọng: Ranh giới trang có thể xảy ra bên trong một phiên.

Dữ liệu mẫu

Nhằm mục đích minh hoạ, chúng tôi sẽ sử dụng dữ liệu mẫu sau đây. Trong ví dụ này, người dùng tương tác với trang web trong 6 phiên trong khoảng thời gian 3 ngày.

Ngày	Mã phiên	Nhãn sự kiện	Thời gian
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

Trang đơn

Nếu bạn đưa ra yêu cầu hoạt động của người dùng có pageSize tối thiểu là 18, thì tất cả dữ liệu sẽ được phân phối trong một trang và sẽ có dạng như sau:

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"}
                }]
        }]
}

Lưu ý: Chúng tôi đã bỏ qua nhiều trường để trình bày ngắn gọn; ví dụ này chỉ nhằm trình bày cách nhóm các hoạt động và phiên không theo quy tắc.

Nhiều trang

Tuy nhiên, nếu kích thước trang của bạn là 5, thì dữ liệu này sẽ được chia thành 4 trang phản hồi:

Ngày	Mã phiên	Nhãn sự kiện	Thời gian
Trang 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
Trang 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
Trang 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
Trang 4:
2018-11-25	6	B	13:09
2018-11-25	6	C	13:12
2018-11-25	6	D	13:23

Lưu ý: Các hoạt động của người dùng luôn theo thứ tự được sắp xếp, nghĩa là ranh giới giữa các trang sẽ không bao giờ là ngẫu nhiên; nó luôn nằm giữa các phiên và hoạt động tạm thời.

Xin lưu ý rằng phiên 2 được chia thành trang đầu tiên và trang thứ hai, và 2 phiên vào ngày 24 tháng 11 được chia thành trang thứ hai và thứ ba. Các phản hồi sẽ có dạng như sau:

{
    "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"}
                }]
        }]
}

Lấy mẫu dữ liệu

Nếu ứng dụng đã tích luỹ một lượng lớn dữ liệu cho phạm vi ngày đã yêu cầu, thì API có thể chỉ trả về một tập hợp con các hoạt động được lấy mẫu. Khi điều này xảy ra, trường sampleRate sẽ cho biết tỷ lệ phần trăm hoạt động của người dùng được trả về.

Cách hệ thống lấy mẫu dữ liệu

Dữ liệu người dùng được lấy mẫu ở cấp hoạt động. Ví dụ: với tỷ lệ lấy mẫu là 50% (0.5), một nửa số hoạt động của người dùng sẽ xuất hiện trong phản hồi.

Các hoạt động lấy mẫu này được chọn tuỳ ý; API không đảm bảo về việc lấy mẫu ngẫu nhiên, cũng như việc lấy mẫu tỷ lệ thuận giữa các hoạt động trong phạm vi ngày nhất định.

Ngăn việc lấy mẫu dữ liệu

Vì API này coi một phiên chỉ là một tập hợp các hoạt động, nên mọi phiên mà không có hoạt động nào xuất hiện trong tập hợp được lấy mẫu sẽ không xuất hiện trong phản hồi. Nếu bạn cần một danh sách đầy đủ các phiên hoạt động hoặc hoạt động, hãy thực hiện các yêu cầu tiếp theo có phạm vi ngày nhỏ hơn.

Ví dụ: nếu bạn yêu cầu dữ liệu từ 2018-01-01 đến 2018-12-31 và phản hồi cho biết tốc độ lấy mẫu là 0.25, hãy chia phạm vi ngày được yêu cầu thành 4 phần, sao cho mỗi phần hy vọng sẽ chứa khoảng một phần tư dữ liệu gốc:

• 2018-01-01 đến 2018-03-31
• 2018-04-01 đến 2018-06-30
• 2018-07-01 đến 2018-09-30
• 2018-10-01 đến 2018-12-31

Lưu ý: Do có thể phân cụm dữ liệu ngẫu nhiên, nên các dải con này cũng có thể được lấy mẫu. Ví dụ: nếu hầu hết dữ liệu của người dùng xảy ra trong phạm vi ngày từ 2018-01-01 đến 2018-03-31, bạn có thể phải thực hiện thêm yêu cầu cho đến khi có tất cả dữ liệu chưa được lấy mẫu.