Este documento descreve vários recursos avançados da API Data v1 do Google Analytics. Para uma referência detalhada da API, consulte a Referência da API.
Listar definições personalizadas e criar relatórios
A API Data pode criar relatórios sobre dimensões e métricas personalizadas registradas. O método da API Metadata pode ser usado para listar os nomes da API das definições personalizadas registradas da sua propriedade. Por exemplo, esses nomes de API podem ser usados em solicitações de relatório para o método runReport.
As seções a seguir mostram exemplos de cada tipo de definição personalizada. Nesses exemplos, substitua GA4_PROPERTY_ID
pelo ID da propriedade.
Dimensões personalizadas no escopo do evento
Etapa 1:consulte o método da API de metadados com seu ID da propriedade.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Etapa 2:encontre a dimensão personalizada no escopo do evento em que você quer criar relatórios usando a resposta. Se a dimensão não estiver presente, registre-a.
"dimensions": [
...
{
"apiName": "customEvent:achievement_id",
"uiName": "Achievement ID",
"description": "An event scoped custom dimension for your Analytics property."
},
...
],
Etapa 3:incluir a dimensão personalizada em uma solicitação de relatório Este é um exemplo de solicitação para o método 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" }]
}
Dimensões personalizadas no escopo do usuário
Etapa 1:consulte o método da API de metadados com seu ID da propriedade.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Etapa 2:encontre a dimensão personalizada no escopo do usuário que você quer usar para criar relatórios usando a resposta. Se a dimensão não estiver presente, registre-a.
"dimensions": [
...
{
"apiName": "customUser:last_level",
"uiName": "Last level",
"description": "A user property for your Analytics property."
},
...
],
Etapa 3:incluir a dimensão personalizada em uma solicitação de relatório Este é um exemplo de solicitação para o método 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" }]
}
Métricas personalizadas no escopo no evento
Etapa 1:consulte o método da API de metadados com seu ID da propriedade.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Etapa 2:encontre a métrica personalizada no escopo do evento que você quer usar para criar relatórios a partir da resposta. Registre a métrica se ela não estiver presente.
"metrics": [
...
{
"apiName": "customEvent:credits_spent",
"uiName": "Credits Spent",
"description": "An event scoped custom metric for your Analytics property.",
"type": "TYPE_STANDARD"
},
...
],
Etapa 3: inclua a métrica personalizada em uma solicitação de relatório. Este é um exemplo de solicitação para o método 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" }]
}
Métricas de taxa de eventos principais para um evento principal
Etapa 1:consulte o método da API de metadados com seu ID da propriedade.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Etapa 2:encontre a métrica "Key Event Rate" de um evento importante em que você quer criar relatórios a partir da resposta. Se o evento de tecla não estiver presente, você vai precisar configurar o evento de tecla.
"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",
},
...
],
Etapa 3:inclua a métrica de taxa de evento principal em uma solicitação de relatório. Veja a seguir um exemplo de solicitação para o método 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" }]
}
Médias da métrica personalizada no escopo do evento
Etapa 1:consulte o método da API de metadados com seu ID da propriedade.
GET https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/metadata
Etapa 2:encontre a média da métrica personalizada no escopo do evento que você quer usar para criar relatórios a partir da resposta. Registre a métrica se ela não estiver presente.
"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"
},
...
],
Etapa 3: inclua a média da métrica personalizada em uma solicitação de relatório. Este é um exemplo de solicitação para o método 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" }]
}
Exemplos de relatório de coorte
Os relatórios de coorte criam uma série temporal de retenção de usuários. Para ver a documentação detalhada de cada campo da API, consulte a referência da REST para CohortSpec.
Criar um relatório de coorte
Confira um exemplo de relatório de coorte em que:
- A coorte são usuários com um
firstSessionDate
de2020-12-01
. Isso é configurado pelo objetocohorts
. As dimensões e métricas na resposta do relatório serão baseadas apenas nos usuários da coorte. - O relatório de coorte mostrará três colunas. Isso é configurado pelos objetos de dimensões e métricas.
- A dimensão
cohort
é o nome da coorte. - A dimensão
cohortNthDay
é o número de dias desde2020-12-01
. - A métrica
cohortActiveUsers
é o número de usuários que ainda estão ativos.
- A dimensão
- O objeto
cohortsRange
especifica que o relatório precisa conter dados de eventos a partir de2020-12-01
e terminando em2020-12-06
para essa coorte.- Quando uma granularidade de
DAILY
é usada, a dimensãocohortNthDay
é recomendada para fins de consistência.
- Quando uma granularidade de
A solicitação de relatório para a coorte é:
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"
}
},
}
Para essa solicitação, um exemplo de resposta de relatório é:
{
"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
}
A partir dessa resposta do relatório, segue um gráfico para este Relatório de coorte. Um insight desse relatório é que a maior queda no número de usuários ativos nessa coorte ocorre entre o primeiro e o segundo dia.
Várias coortes e fração de retenção de usuários
A aquisição e retenção de usuários são maneiras de expandir seu site ou app. Os relatórios de coorte se concentram na retenção de usuários. Neste exemplo, o relatório mostra que essa propriedade melhorou a retenção de usuários de quatro dias em 10% ao longo de duas semanas.
Para criar esse relatório, especificamos três coortes: a primeira com um firstSessionDate
de 2020-11-02
, a segunda com um firstSessionDate
de 2020-11-09
e a terceira com um firstSessionDate
de 2020-11-16
. Como o
número de usuários na sua propriedade será diferente durante esses três dias, comparamos a métrica fração de retenção de usuários da coorte de
cohortActiveUsers/cohortTotalUsers
em vez de usar a métrica
cohortActiveUsers
direta.
A solicitação de relatório para essas coortes é:
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"
}
},
}
Para essa solicitação, um exemplo de resposta de relatório é:
{
"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
}
A partir dessa resposta do relatório, segue um gráfico para este Relatório de coorte. Um insight desse relatório é que a retenção de usuários de quatro dias aumentou em 10% ao longo de duas semanas. A coorte posterior com firstSessionDate
de 2020-11-16
excede a retenção da coorte anterior com firstSessionDate
de 2020-11-02
.
Coortes semanais e uso de coortes com outros recursos da API
Para remover a variação diária no comportamento do usuário, use coortes semanais. Nos relatórios
de coorte semanais, todos os usuários com firstSessionDate
na mesma semana formam a
coorte. As semanas começam no domingo e terminam no sábado. Também neste relatório, estamos
repartindo a coorte para comparar os usuários com atividade na Rússia com os que têm
atividade no México. Esse fracionamento usa a dimensão country
e um
dimensionFilter
para considerar apenas os dois países.
A solicitação de relatório para essas coortes é:
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"
}
},
}
Para essa solicitação, um exemplo de resposta de relatório é:
{
"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
}
A partir dessa resposta do relatório, segue um gráfico deste Relatório de coorte. Com base nesse relatório, essa propriedade está se saindo melhor em reter usuários com atividade no México do que usuários com atividade na Rússia.
Comparações
Com as comparações, você pode avaliar subconjuntos dos seus dados lado a lado. Para definir comparações, especifique o campo comparisons
em uma definição de relatório. O recurso de comparações da API Data é semelhante às Comparações no front-end do Google Analytics.
Para ver a documentação detalhada de cada campo da API, consulte a referência da REST para comparação.
Criar uma comparação
É possível criar uma comparação separada para cada conjunto de dados que você queira comparar. Por exemplo, para comparar dados do app e da Web, crie uma comparação para dados do Android e do iOS e outra comparação para dados da Web.
Confira um exemplo de relatório que define duas comparações e retorna usuários ativos divididos por país.
A primeira comparação, chamada "Tráfego do app", usa inListFilter
para fazer a correspondência da dimensão platform
com os valores "iOS" e "Android". A segunda comparação, chamada "Tráfego da Web", usa stringFilter
para associar a dimensão platform
a "Web".
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"
}
]
}
Para todas as solicitações que usam o recurso de comparações, o campo comparison
é
adicionado automaticamente ao relatório gerado. Esse campo contém o nome da comparação fornecida na solicitação.
Veja um snippet de exemplo de uma resposta que contém comparações:
{
"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"
}
]
},
...
],
...
}