이 문서에서는 Google 애널리틱스 Data API v1의 여러 고급 기능을 설명합니다. API에 관한 자세한 참조는 API 참조를 확인하세요.
맞춤 정의 나열 및 보고서 만들기
Data API는 등록된 맞춤 측정기준 및 맞춤 측정항목에 대한 보고서를 만들 수 있습니다. Metadata API 메서드를 사용하여 속성에 등록된 맞춤 정의의 API 이름을 나열할 수 있습니다. 예를 들어 runReport 메서드에 대한 보고서 요청에서 이러한 API 이름을 사용할 수 있습니다.
다음 섹션에서는 각 맞춤 정의 유형의 예를 보여줍니다. 이 예시에서 GA4_PROPERTY_ID
를 속성 ID로 바꿉니다.
이벤트 범위 맞춤 측정기준
1단계: 속성 ID로 Metadata API 메서드를 쿼리합니다.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
2단계: 응답에서 보고서를 만들려는 이벤트 범위 맞춤 측정기준을 찾습니다. 측정기준이 없는 경우 측정기준을 등록해야 합니다.
"dimensions": [
...
{
"apiName": "customEvent:achievement_id",
"uiName": "Achievement ID",
"description": "An event scoped custom dimension for your Analytics property."
},
...
],
3단계: 보고서 요청에 맞춤 측정기준을 포함합니다. 다음은 runReport 메서드에 대한 샘플 요청입니다.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [{ "name": "customEvent:achievement_id" }],
"metrics": [{ "name": "eventCount" }]
}
사용자 범위 맞춤 측정기준
1단계: 속성 ID로 Metadata API 메서드를 쿼리합니다.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
2단계: 응답에서 보고서를 만들려는 사용자 범위 맞춤 측정기준을 찾습니다. 측정기준이 없는 경우 측정기준을 등록해야 합니다.
"dimensions": [
...
{
"apiName": "customUser:last_level",
"uiName": "Last level",
"description": "A user property for your Analytics property."
},
...
],
3단계: 보고서 요청에 맞춤 측정기준을 포함합니다. 다음은 runReport 메서드에 대한 샘플 요청입니다.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"entity": { "propertyId": "GA4_PROPERTY_ID" },
"dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "customUser:last_level" }],
"metrics": [{ "name": "activeUsers" }]
}
이벤트 범위 맞춤 측정항목
1단계: 속성 ID로 Metadata API 메서드를 쿼리합니다.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
2단계: 응답에서 보고서를 만들려는 이벤트 범위 맞춤 측정항목을 찾습니다. 측정항목이 없으면 측정항목을 등록해야 합니다.
"metrics": [
...
{
"apiName": "customEvent:credits_spent",
"uiName": "Credits Spent",
"description": "An event scoped custom metric for your Analytics property.",
"type": "TYPE_STANDARD"
},
...
],
3단계: 보고서 요청에 맞춤 측정항목을 포함합니다. 다음은 runReport 메서드에 대한 샘플 요청입니다.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "customEvent:credits_spent" }]
}
주요 이벤트 1개의 주요 이벤트 비율 측정항목
1단계: 속성 ID로 Metadata API 메서드를 쿼리합니다.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
2단계: 응답에서 보고서를 만들려는 주요 이벤트 1개의 주요 이벤트 비율 측정항목을 찾습니다. 키 이벤트가 없으면 키 이벤트를 설정해야 합니다.
"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",
},
...
],
3단계: 보고서 요청에 주요 이벤트 비율 측정항목을 포함합니다. 다음은 runReport 메서드에 대한 샘플 요청입니다.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "sessionKeyEventRate:add_to_cart" }]
}
이벤트 범위 맞춤 측정항목 평균
1단계: 속성 ID로 Metadata API 메서드를 쿼리합니다.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
2단계: 응답에서 보고서를 만들려는 이벤트 범위 맞춤 측정항목 평균을 찾습니다. 측정항목이 없으면 측정항목을 등록해야 합니다.
"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"
},
...
],
3단계: 보고서 요청에 맞춤 측정항목 평균을 포함합니다. 다음은 runReport 메서드에 대한 샘플 요청입니다.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
"dimensions": [{ "name": "eventName" }],
"metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}
동질 집단 보고서의 예
동질 집단 보고서에서는 동질 집단의 사용자 유지율을 시계열로 확인할 수 있습니다. 각 API 필드에 관한 자세한 내용은 CohortSpec의 REST 참조를 확인하세요.
동질 집단 보고서 만들기
다음은 동질 집단 보고서 샘플입니다.
- 동질 집단은
firstSessionDate
가2020-12-01
인 사용자로,cohorts
객체로 구성됩니다. 보고서 응답의 측정기준과 측정항목은 동질 집단의 사용자만을 기반으로 합니다. - 동질 집단 보고서에는 3개의 열이 표시됩니다. 이 열은 측정기준 및 측정항목 객체로 구성됩니다.
- 측정기준
cohort
은 동질 집단의 이름입니다. cohortNthDay
측정기준은2020-12-01
이후 경과한 일수입니다.cohortActiveUsers
측정항목은 아직 활성 상태인 사용자 수입니다.
- 측정기준
cohortsRange
객체는 이 동질 집단에 대해2020-12-01
에서 시작하고2020-12-06
로 끝나는 이벤트 데이터를 보고서에 포함해야 함을 지정합니다.DAILY
의 세부사항을 사용하는 경우 일관성을 위해 측정기준cohortNthDay
를 사용하는 것이 좋습니다.
동질 집단에 대한 보고서 요청은 다음과 같습니다.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_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"
}
},
}
이 요청에 대한 보고서 응답의 예는 다음과 같습니다.
{
"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
}
이 보고서 응답에서 이 동질 집단 보고서의 차트가 이어집니다. 이 보고서의 유용한 정보에 따르면 이 동질 집단의 활성 사용자 수가 1일과 2일 사이가 가장 크다는 것입니다.
여러 동질 집단 및 사용자 유지율
사용자 획득 및 유지는 웹사이트 또는 앱을 성장시키는 방법입니다. 동질 집단 보고서는 사용자 유지에 초점을 맞춥니다. 이 예의 보고서는 이 속성이 2주 동안 4일 사용자 유지율이 10% 향상되었음을 보여줍니다.
이 보고서를 만들기 위해 세 가지 동질 집단을 지정합니다. 첫 번째는 firstSessionDate
가 2020-11-02
이고, 두 번째는 firstSessionDate
가 2020-11-09
이고, 세 번째는 firstSessionDate
가 2020-11-16
입니다. 이 3일 동안 속성의 사용자 수가 달라지므로 직접 cohortActiveUsers
측정항목을 사용하는 대신 동질 집단의 사용자 유지율 비율 측정항목 cohortActiveUsers/cohortTotalUsers
를 비교합니다.
이러한 동질 집단에 대한 보고서 요청은 다음과 같습니다.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_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"
}
},
}
이 요청에 대한 보고서 응답의 예는 다음과 같습니다.
{
"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
}
이 보고서 응답에서 이 동질 집단 보고서의 차트가 이어집니다. 이 보고서를 통해 4일 사용자 유지율이 2주 동안 10% 증가한 것으로 나타났습니다. firstSessionDate
가 2020-11-16
인 후반 사용자 집단이 firstSessionDate
가 2020-11-02
인 이전 동질 집단의 유지율을 초과합니다.
주간 사용자 집단 및 다른 API 기능과 함께 사용자 집단 사용
사용자 행동의 일상적인 편차를 제거하려면 주간 동질 집단을 사용하세요. 주간 동질 집단 보고서에서 같은 주의 firstSessionDate
이 있는 모든 사용자가 동질 집단을 형성합니다. 주는 일요일에 시작하여 토요일에 끝납니다. 또한 이 보고서에서는 사용자 집단을 분류하여 러시아에서의 활동이 있는 사용자와 멕시코에서의 활동이 있는 사용자를 비교합니다. 이 슬라이싱에서는 country
측정기준과 dimensionFilter
을 사용하여 두 국가만 고려합니다.
이러한 동질 집단에 대한 보고서 요청은 다음과 같습니다.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_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"
}
},
}
이 요청에 대한 보고서 응답의 예는 다음과 같습니다.
{
"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
}
이 보고서 응답에서 동질 집단 보고서의 차트가 이어집니다. 이 보고서에 따르면 이 속성은 러시아에서 활동이 있는 사용자보다 멕시코에서 활동하는 사용자를 유지하는 데 더 효과적입니다.
비교
비교를 통해 데이터의 하위 집합을 나란히 평가할 수 있습니다. 보고서 정의에서 comparisons
필드를 지정하여 비교를 정의할 수 있습니다. Data API의 비교 기능은 Google 애널리틱스 프런트엔드의 비교와 비슷합니다.
각 API 필드에 관한 자세한 내용은 비교를 위한 REST 참조를 확인하세요.
비교 만들기
비교하려는 각 데이터 세트에 대해 별도의 비교를 만들 수 있습니다. 예를 들어 앱 데이터와 웹 데이터를 비교하려면 Android 및 iOS 데이터에 대한 비교와 웹 데이터에 대한 비교를 하나씩 만들면 됩니다.
다음은 두 가지 비교를 정의하고 국가별로 분류된 활성 사용자를 반환하는 샘플 보고서입니다.
'앱 트래픽'이라는 첫 번째 비교에서는 inListFilter
를 사용하여 platform
측정기준을 'iOS' 및 'Android' 값과 일치시킵니다. '웹 트래픽'이라는 두 번째 비교에서는 stringFilter
를 사용하여 platform
측정기준을 '웹'과 일치시킵니다.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_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"
}
]
}
비교 기능을 사용하는 모든 요청의 경우 comparison
필드가 생성된 보고서에 자동으로 추가됩니다. 이 필드에는 요청에 제공된 비교 이름이 포함됩니다.
다음은 비교가 포함된 응답의 샘플 스니펫입니다.
{
"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"
}
]
},
...
],
...
}