Tài liệu này mô tả một số tính năng nâng cao của API Dữ liệu Google Analytics phiên bản 1. Để biết thông tin tham khảo chi tiết về API, hãy xem Tài liệu tham khảo về API.
Liệt kê các định nghĩa tuỳ chỉnh và tạo báo cáo
Data API có thể tạo báo cáo về Phương diện tuỳ chỉnh và Chỉ số tuỳ chỉnh đã đăng ký. Bạn có thể dùng Phương thức Metadata API để liệt kê tên API của các Định nghĩa tuỳ chỉnh đã đăng ký của Tài sản. Bạn có thể sử dụng các tên API này trong Yêu cầu báo cáo cho phương thức runReport, chẳng hạn.
Các phần sau đây trình bày ví dụ cho từng loại Định nghĩa tuỳ chỉnh. Trong các ví dụ này, hãy thay thế GA_PROPERTY_ID bằng Mã tài sản của bạn.
Thứ nguyên tùy chỉnh ở phạm vi sự kiện
Bước 1: Truy vấn Phương thức Metadata API bằng mã tài sản của bạn.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
Bước 2: Tìm Phương diện tuỳ chỉnh ở phạm vi sự kiện mà bạn muốn tạo báo cáo trong phản hồi. Nếu không có phương diện này, bạn cần đăng ký phương diện.
"dimensions": [
...
{
"apiName": "customEvent:achievement_id",
"uiName": "Achievement ID",
"description": "An event scoped custom dimension for your Analytics property."
},
...
],
Bước 3: Thêm phương diện tuỳ chỉnh vào yêu cầu báo cáo. Sau đây là một yêu cầu mẫu đối với phương thức runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [{ "name": "customEvent:achievement_id" }],
"metrics": [{ "name": "eventCount" }]
}
Phương diện tuỳ chỉnh trong phạm vi người dùng
Bước 1: Truy vấn Phương thức Metadata API bằng mã tài sản của bạn.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
Bước 2: Tìm Phương diện tuỳ chỉnh ở phạm vi người dùng mà bạn muốn tạo báo cáo trong phản hồi. Nếu không có phương diện này, bạn cần đăng ký phương diện.
"dimensions": [
...
{
"apiName": "customUser:last_level",
"uiName": "Last level",
"description": "A user property for your Analytics property."
},
...
],
Bước 3: Thêm phương diện tuỳ chỉnh vào yêu cầu báo cáo. Sau đây là một yêu cầu mẫu đối với phương thức runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"entity": { "propertyId": "GA_PROPERTY_ID" },
"dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "customUser:last_level" }],
"metrics": [{ "name": "activeUsers" }]
}
Chỉ số tùy chỉnh ở phạm vi sự kiện
Bước 1: Truy vấn Phương thức Metadata API bằng mã tài sản của bạn.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
Bước 2: Tìm Chỉ số tuỳ chỉnh ở phạm vi sự kiện mà bạn muốn tạo báo cáo trong phản hồi. Nếu không có chỉ số này, bạn cần đăng ký chỉ số.
"metrics": [
...
{
"apiName": "customEvent:credits_spent",
"uiName": "Credits Spent",
"description": "An event scoped custom metric for your Analytics property.",
"type": "TYPE_STANDARD"
},
...
],
Bước 3: Đưa chỉ số tuỳ chỉnh vào yêu cầu báo cáo. Sau đây là một yêu cầu mẫu đối với phương thức runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "customEvent:credits_spent" }]
}
Chỉ số tỷ lệ sự kiện quan trọng cho một sự kiện quan trọng
Bước 1: Truy vấn Phương thức Metadata API bằng Mã tài sản của bạn.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
Bước 2: Tìm Chỉ số tỷ lệ sự kiện chính cho một Sự kiện chính mà bạn muốn tạo báo cáo trong phản hồi. Nếu không có sự kiện quan trọng, bạn cần thiết lập sự kiện quan trọng.
"metrics": [
...
{
"apiName": "sessionKeyEventRate:add_to_cart",
"uiName": "Session key event rate for add_to_cart",
"description": "The percentage of sessions in which a specific key event was triggered",
},
...
],
Bước 3: Thêm chỉ số tỷ lệ sự kiện chính vào yêu cầu báo cáo. Sau đây là một yêu cầu mẫu đối với phương thức runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "sessionKeyEventRate:add_to_cart" }]
}
Giá trị trung bình của chỉ số tuỳ chỉnh ở phạm vi sự kiện
Bước 1: Truy vấn Phương thức Metadata API bằng mã tài sản của bạn.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata
Bước 2: Tìm Chỉ số tuỳ chỉnh ở phạm vi sự kiện mà bạn muốn tạo báo cáo trong phản hồi. Nếu không có chỉ số này, bạn cần đăng ký chỉ số.
"metrics": [
...
{
"apiName": "averageCustomEvent:credits_spent",
"uiName": "Average Credits Spent",
"description": "The average of an event scoped custom metric for your Analytics property.",
"type": "TYPE_STANDARD"
},
...
],
Bước 3: Đưa chỉ số tuỳ chỉnh trung bình vào yêu cầu báo cáo. Sau đây là một yêu cầu mẫu đối với phương thức runReport.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}
Ví dụ về báo cáo nhóm thuần tập
Báo cáo nhóm thuần tập tạo chuỗi thời gian về tỷ lệ giữ chân người dùng cho nhóm thuần tập. Để biết tài liệu chi tiết về từng trường API, hãy xem tài liệu tham khảo REST cho CohortSpec.
Tạo báo cáo nhóm thuần tập
Sau đây là một báo cáo nhóm thuần tập mẫu, trong đó:
- Nhóm thuần tập là những người dùng có
firstSessionDatelà2020-12-01; nhóm này được đối tượngcohortsđịnh cấu hình. Các phương diện và chỉ số trong phản hồi báo cáo sẽ chỉ dựa trên người dùng của nhóm thuần tập. - Báo cáo когорта sẽ có 3 cột; báo cáo này được định cấu hình bằng các đối tượng phương diện và chỉ số.
- Phương diện
cohortlà tên của nhóm когорта. - Phương diện
cohortNthDaylà số ngày kể từ2020-12-01. - Chỉ số
cohortActiveUserslà số người dùng vẫn đang hoạt động.
- Phương diện
- Đối tượng
cohortsRangechỉ định rằng báo cáo phải chứa dữ liệu sự kiện bắt đầu từ2020-12-01và kết thúc tại2020-12-06cho когорта này.- Khi sử dụng độ chi tiết là
DAILY, bạn nên dùng phương diệncohortNthDayđể đảm bảo tính nhất quán.
- Khi sử dụng độ chi tiết là
Yêu cầu báo cáo cho nhóm thuần tập là:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dimensions": [{ "name": "cohort" }, { "name": "cohortNthDay" }],
"metrics": [{ "name": "cohortActiveUsers" }],
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-12-01", "endDate": "2020-12-01" }
}
],
"cohortsRange": {
"endOffset": 5,
"granularity": "DAILY"
}
},
}
Đối với yêu cầu này, phản hồi của báo cáo mẫu là:
{
"dimensionHeaders": [
{ "name": "cohort" }, { "name": "cohortNthDay" }
],
"metricHeaders": [
{ "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
],
"rows": [
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
"metricValues": [{ "value": "293" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
"metricValues": [{ "value": "143" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
"metricValues": [{ "value": "123" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
"metricValues": [{ "value": "92" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0005" }],
"metricValues": [{ "value": "86" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
"metricValues": [{ "value": "83" }]
}
],
"metadata": {},
"rowCount": 6
}
Từ phản hồi báo cáo này, một biểu đồ cho Báo cáo nhóm thuần tập này sẽ xuất hiện. Thông tin chi tiết từ báo cáo này là số người dùng đang hoạt động giảm mạnh nhất đối với nhóm thuần tập này là từ ngày đầu tiên đến ngày thứ hai.
Nhiều nhóm và tỷ lệ giữ chân người dùng
Thu nạp và giữ chân người dùng là những cách để phát triển Trang web hoặc Ứng dụng của bạn. Báo cáo nhóm thuần tập tập trung vào việc giữ chân người dùng. Trong ví dụ này, báo cáo cho thấy tài sản này đã cải thiện tỷ lệ giữ chân người dùng trong 4 ngày thêm 10% trong vòng 2 tuần.
Để tạo báo cáo này, chúng tôi chỉ định 3 nhóm когорта: nhóm đầu tiên có firstSessionDate là 2020-11-02, nhóm thứ hai có firstSessionDate là 2020-11-09 và nhóm thứ ba có firstSessionDate là 2020-11-16. Vì số lượng người dùng trên tài sản của bạn sẽ khác nhau trong 3 ngày này, nên chúng tôi so sánh chỉ số tỷ lệ giữ chân người dùng của nhóm là cohortActiveUsers/cohortTotalUsers thay vì sử dụng chỉ số cohortActiveUsers trực tiếp.
Yêu cầu báo cáo cho các nhóm này là:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dimensions": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
"metrics": [
{
"name": "cohortRetentionFraction",
"expression": "cohortActiveUsers/cohortTotalUsers"
}
],
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-02", "endDate": "2020-11-02" }
},
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-09", "endDate": "2020-11-09" }
},
{
"dimension": "firstSessionDate",
"dateRange": { "startDate": "2020-11-16", "endDate": "2020-11-16" }
}
],
"cohortsRange": {
"endOffset": 4,
"granularity": "DAILY"
}
},
}
Đối với yêu cầu này, phản hồi của báo cáo mẫu là:
{
"dimensionHeaders": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
"metricHeaders": [{
"name": "cohortRetentionFraction",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0000" }],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0001" }],
"metricValues": [{ "value": "0.308" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0001" }],
"metricValues": [{ "value": "0.272" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0002" }],
"metricValues": [{ "value": "0.257" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
"metricValues": [{ "value": "0.248" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0003" }],
"metricValues": [{ "value": "0.235" }]
},
{
"dimensionValues": [{ "value": "cohort_2" },{ "value": "0004" }],
"metricValues": [{ "value": "0.211" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0002" }],
"metricValues": [{ "value": "0.198" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
"metricValues": [{ "value": "0.172" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0003" }],
"metricValues": [{ "value": "0.167" }]
},
{
"dimensionValues": [{ "value": "cohort_1" },{ "value": "0004" }],
"metricValues": [{ "value": "0.155" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
"metricValues": [{ "value": "0.141" }]
},
{
"dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
"metricValues": [{ "value": "0.118" }]
}
],
"metadata": {},
"rowCount": 15
}
Từ phản hồi báo cáo này, một biểu đồ cho Báo cáo nhóm thuần tập này sẽ xuất hiện. Một thông tin chi tiết từ báo cáo này là tỷ lệ giữ chân người dùng trong 4 ngày đã tăng 10% trong vòng 2 tuần. Nhóm sau có firstSessionDate là 2020-11-16 vượt quá mức giữ chân của nhóm trước có firstSessionDate là 2020-11-02.
Nhóm thuần tập theo tuần và sử dụng nhóm thuần tập với các tính năng khác của API
Để loại bỏ sự khác biệt về hành vi của người dùng theo từng ngày, hãy sử dụng các nhóm thuần tập hằng tuần. Trong báo cáo nhóm thuần tập theo tuần, tất cả người dùng có firstSessionDate trong cùng một tuần sẽ tạo thành nhóm thuần tập. Tuần bắt đầu vào Chủ Nhật và kết thúc vào Thứ Bảy. Trong báo cáo này, chúng ta cũng đang phân đoạn nhóm thuần tập để so sánh những người dùng có hoạt động ở Nga với những người dùng có hoạt động ở Mexico. Việc phân đoạn này sử dụng phương diện country và dimensionFilter để chỉ xem xét 2 quốc gia.
Yêu cầu báo cáo cho các nhóm này là:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"dimensions": [
{ "name": "cohort" },
{ "name": "cohortNthWeek" },
{ "name": "country" }
],
"metrics": [{ "name": "cohortActiveUsers" }],
"dimensionFilter": {
"filter": {
"fieldName": "country",
"inListFilter": {
"values": [ "Russia", "Mexico" ]
}
}
},
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"dateRange": {
"startDate": "2020-10-04",
"endDate": "2020-10-10"
}
}
],
"cohortsRange": {
"endOffset": 5,
"granularity": "WEEKLY"
}
},
}
Đối với yêu cầu này, phản hồi của báo cáo mẫu là:
{
"dimensionHeaders": [
{ "name": "cohort" },
{ "name": "cohortNthWeek" },
{ "name": "country" }
],
"metricHeaders": [
{ "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
],
"rows": [
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0000" },{ "value": "Russia" }
],
"metricValues": [{ "value": "105" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0000" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "98" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0001" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "35" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0002" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "24" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0001" },{ "value": "Russia" }
],
"metricValues": [{ "value": "23" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0004" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "17" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0003" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "15" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0005" },{ "value": "Mexico" }
],
"metricValues": [{ "value": "15" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0002" },{ "value": "Russia" }
],
"metricValues": [{ "value": "3" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0003" },{ "value": "Russia" }
],
"metricValues": [{ "value": "1" }]
},
{
"dimensionValues": [
{ "value": "cohort_0" },{ "value": "0004" },{ "value": "Russia" }
],
"metricValues": [{ "value": "1" }]
}
],
"metadata": {},
"rowCount": 11
}
Từ phản hồi báo cáo này, một biểu đồ của Báo cáo nhóm thuần tập này sẽ xuất hiện. Dựa trên báo cáo này, tài sản này đang hoạt động hiệu quả hơn trong việc giữ chân người dùng có hoạt động ở Mexico so với người dùng có hoạt động ở Nga.
Phép so sánh
Khi dùng phép so sánh, bạn có thể đánh giá các nhóm dữ liệu nhỏ cùng một lúc. Bạn có thể xác định các phép so sánh bằng cách chỉ định trường comparisons trong một định nghĩa báo cáo. Tính năng So sánh của Data API tương tự như Tính năng so sánh trong giao diện người dùng Google Analytics.
Để biết tài liệu chi tiết về từng trường API, hãy xem tài liệu tham khảo REST cho So sánh.
Tạo thông tin so sánh
Bạn có thể tạo một phép so sánh riêng cho từng tập dữ liệu mà bạn muốn so sánh. Ví dụ: để so sánh dữ liệu web và ứng dụng, bạn có thể tạo một phép so sánh cho dữ liệu Android và iOS, đồng thời tạo một phép so sánh khác cho dữ liệu web.
Sau đây là một báo cáo mẫu xác định 2 thông tin so sánh và trả về số người dùng đang hoạt động được phân tích theo quốc gia.
Phép so sánh đầu tiên có tên là "Lưu lượng truy cập từ ứng dụng" đang sử dụng inListFilter để so khớp phương diện platform với các giá trị "iOS" và "Android". Thông tin so sánh thứ hai có tên "Lưu lượng truy cập trang web" sử dụng stringFilter để so khớp phương diện platform với "web".
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
"comparisons": [
{
"name": "App traffic",
"dimensionFilter": {
"filter": {
"fieldName": "platform",
"inListFilter": {
"values": [
"iOS",
"Android"
]
}
}
}
},
{
"name": "Web traffic",
"dimensionFilter": {
"filter": {
"fieldName": "platform",
"stringFilter": {
"matchType": "EXACT",
"value": "web"
}
}
}
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
],
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
]
}
Đối với tất cả các yêu cầu sử dụng tính năng so sánh, trường comparison sẽ tự động được thêm vào báo cáo đã tạo. Trường này chứa tên của phép so sánh được cung cấp trong yêu cầu.
Dưới đây là một đoạn mã mẫu của phản hồi chứa các so sánh:
{
"dimensionHeaders": [
{
"name": "comparison"
},
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "Web traffic"
},
{
"value": "United States"
}
],
"metricValues": [
{
"value": "638572"
}
]
},
{
"dimensionValues": [
{
"value": "Web traffic"
},
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "376578"
}
]
},
{
"dimensionValues": [
{
"value": "App traffic"
},
{
"value": "United States"
}
],
"metricValues": [
{
"value": "79527"
}
]
},
...
],
...
}