Com a API User Activity, o proprietário de uma propriedade do Google Analytics recupera todos os dados de medição do Analytics associados a um único usuário. Especificamente, a API recupera todos os dados de medição associados a um User-ID ou Client-ID específico.
Fazer uma solicitação de atividade do usuário
Para fazer uma solicitação de atividade do usuário, construa um objeto de solicitação com os seguintes campos:
O Client-ID ou User-ID associado ao usuário
- Consulte Cookies e identificação do usuário para detalhes sobre como procurar esses campos.
Um ID da vista do Google Analytics que contém os dados associados ao usuário.
- Você pode usar o Explorador da conta para procurar o ID da sua vista.
Embora não seja obrigatório, você provavelmente precisará de um período para os dados em que tem interesse. Por padrão, a API lista a atividade do usuário na última semana.
Exemplo de solicitação
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",
}
}
Exemplo de resposta
{
"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
}
Sessões e atividades
Os dados de atividade do usuário são agrupados por sessão. Cada
sessão contém informações gerais
sobre a sessão, como o ID e a data, além de uma lista
de atividades do usuário.
As atividades do usuário em uma sessão consistem em cada "hit" pelo qual o usuário foi responsável. Isso inclui visualizações de página, eventos de e-commerce e eventos personalizados enviados usando gtag(...)
ou ga(...)
.
Paginação
A API User Activity usa paginação para dividir grandes conjuntos de dados em várias solicitações e respostas. No entanto, como os dados retornados pela API são estruturados hierarquicamente, algumas considerações especiais precisam ser tomadas pelo desenvolvedor para agrupar os dados corretamente.
O tipo básico de "linha" para a paginação é a atividade. Como os dados do usuário são agrupados por sessão, isso significa que um limite de página pode ocorrer dentro de uma sessão, e essa sessão pode ter atividades que abrangem várias páginas.
Dados de amostra
Para fins de demonstração, usaremos os dados de exemplo a seguir. Neste exemplo, o usuário interagiu com o site em seis sessões ao longo de três dias.
Data | ID da sessão | Rótulo do evento | Tempo |
---|---|---|---|
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 |
Página única
Se você fizer uma solicitação de atividade do usuário com um pageSize
de pelo menos 18, os dados
serão enviados em uma única página e terão esta aparência:
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"}
}]
}]
}
Várias páginas
No entanto, se o tamanho da página for 5, esses dados serão divididos em quatro páginas de resposta:
Data | ID da sessão | Rótulo do evento | Tempo |
---|---|---|---|
Página 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 |
Página 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 |
Página 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 |
Página 4: | |||
2018-11-25 | 6 | B | 13:09 |
2018-11-25 | 6 | C | 13:12 |
2018-11-25 | 6 | D | 13:23 |
Observe que a sessão 2 está dividida na primeira e segunda páginas, e as duas sessões em 24 de novembro estão divididas na segunda e terceira páginas. As respostas serão parecidas com estas:
{
"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"}
}]
}]
}
Amostragem de dados
Se um cliente tiver acumulado uma grande quantidade de dados no período solicitado, a API poderá retornar somente um subconjunto de atividades com amostragem. Quando isso
acontecer, o campo sampleRate
vai indicar qual fração das atividades
do usuário foi retornada.
Como é feita a amostragem dos dados
A amostra dos dados do usuário é realizada no nível da atividade. Por exemplo, com uma taxa de amostragem
de 50% (0.5
), metade das atividades do usuário estará presente na
resposta.
Essas atividades de amostra são selecionadas arbitrariamente. A API não oferece garantias sobre amostragem aleatória nem de que a amostragem seja proporcional entre as atividades para o período especificado.
Impedir a amostragem de dados
Como essa API trata uma sessão como simplesmente um conjunto de atividades, as sessões em que nenhuma atividade aparece no conjunto de amostra não aparecerão na resposta. Se você precisar de uma lista abrangente de sessões ou atividades, faça solicitações de acompanhamento com períodos menores.
Por exemplo, se você solicitar dados de 2018-01-01
a 2018-12-31
e a resposta indicar uma taxa de amostragem de 0.25
, divida o período solicitado em quatro partes, de modo que cada parte contenha cerca de um quarto dos dados originais:
2018-01-01
a2018-03-31
- De
2018-04-01
para2018-06-30
- De
2018-07-01
para2018-09-30
2018-10-01
a2018-12-31