API User Activity

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:

  1. O Client-ID ou User-ID associado ao usuário

  2. Um ID da vista do Google Analytics que contém os dados associados ao usuário.

  3. 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:

DataID da sessãoRótulo do eventoTempo
Página 1:
2018-11-231A10:26
2018-11-231B10:32
2018-11-231C10:39
2018-11-232A18:04
2018-11-232B18:11
Página 2:
2018-11-232C18:26
2018-11-243A11:26
2018-11-243B11:29
2018-11-243C11:39
2018-11-243D11:42
Página 3:
2018-11-244A23:50
2018-11-244B23:54
2018-11-255C00:02
2018-11-255D00:13
2018-11-256A13:01
Página 4:
2018-11-256B13:09
2018-11-256C13:12
2018-11-256D13: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 a 2018-03-31
  • De 2018-04-01 para 2018-06-30
  • De 2018-07-01 para 2018-09-30
  • 2018-10-01 a 2018-12-31