Casos de uso avançado

Este documento descreve os recursos avançados da Reporting API v4 do Google Analytics. Para uma referência detalhada da API, leia o Guia de referência.

Introdução

Após a criação de um relatório simples, use estes recursos para criar relatórios avançados:

Tabelas dinâmicas

A Reporting API v4 do Google Analytics permite a geração de Tabelas dinâmicas. Para criar uma solicitação com uma tabela dinâmica, defina o campo Pivot no ReportRequest. O objeto Pivot tem um grupo próprio de dimensões e métricas, além dos campos opcionais startGroup e maxGroupCount para especificar o número de dimensões que serão incluídas na tabela dinâmica.

Solicitação

A chamada da API a seguir solicita sessões por país e exibe os resultados dinamicamente no navegador:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges":
      [
        {
          "startDate": "2014-11-01",
          "endDate": "2014-11-30"
        }
      ],
      "metrics":
      [
        {
          "expression": "ga:sessions"
        }
      ],
      "dimensions":
      [
        {
          "name": "ga:country"
        }
      ],
      "pivots":
      [
        {
          "dimensions":
          [
            {
              "name": "ga:browser"
            }
          ],
          "maxGroupCount": 3,
          "startGroup": 3,
          "metrics":
          [
            {
              "expression": "ga:sessions"
            }
          ]
        }
      ]
    }
  ]
}

Título da coluna de resposta

No objeto report retornado de uma solicitação de tabela dinâmica, o metricHeader possui uma lista de objetos pivotHeaders. Esses objetos têm campos pivotHeaderEntries que definem a ordem dos valores de dimensões dinâmicas e dos valores das métricas correspondentes. Por exemplo:

"columnHeader": {
    "dimensions": [
        "ga:country"
    ],
    "metricHeader": {
        "metricHeaderEntries": [
            {
                "name": "ga:sessions",
                "type": "INTEGER"
            }
        ],
        "pivotHeaders": [
            {
                "pivotHeaderEntries": [
                    {
                        "dimensionNames": [
                            "ga:browser"
                        ],
                        "dimensionValues": [
                            "Internet Explorer"
                        ],
                        "metric": {
                            "name": "ga:sessions",
                            "type": "INTEGER"
                        }
                    },
                    {
                        "dimensionNames": [
                            "ga:browser"
                        ],
                        "dimensionValues": [
                            "Firefox"
                        ],
                        "metric": {
                            "name": "ga:sessions",
                            "type": "INTEGER"
                        }
                    },
                    {
                        "dimensionNames": [
                            "ga:browser"
                        ],
                        "dimensionValues": [
                            "Android Browser"
                        ],
                        "metric": {
                            "name": "ga:sessions",
                            "type": "INTEGER"
                        }
                    }
                ],
                "totalPivotGroupsCount": 7
            }
        ]
    }
},

Linhas de resposta

Cada linha do objeto reportData define uma matriz de objetos dateRangeValue, cada um dos quais contém um conjunto de objetos pivotValue. A ordem dos valores corresponde à ordem das métricas listadas nos títulos da tabela dinâmica no título da coluna de resposta.

"rows": [
    ...
    {
        "dimensions": [
            "United States"
        ],
        "metrics": [
            {
                "pivotValues": [
                    {
                        "values": [
                            "21",
                            "18",
                            "1"
                        ]
                    }
                ],
                "values": [
                    "192"
                ]
            }
        ]
    }
],

É importante ressaltar que existem somente três valores dinâmicos no relatório. Isso ocorre porque o valor de maxGroupCount é três na solicitação original. Poderia existem até sete valores, já que "totalPivotGroupsCount": 7.

Exemplo de linha da tabela dinâmica

No exemplo de resposta acima, a linha associada ao país Estados Unidos está representada na tabela dinâmica a seguir:

País Total de
Sessões
Internet Explorer
Sessões
Firefox
Sessões
Navegador Android
Sessões
Índia 12 3 2 4
Estados Unidos 192 21 18 1
Reino Unido 35 12 2 0

Coortes

Um coorte é um grupo de usuários que compartilham uma característica comum. Por exemplo, todos os usuários com a mesma data de aquisição pertencem ao mesmo coorte. Com o Relatório de análise de coorte, você pode isolar e analisar o comportamento de coortes. Para ver uma lista de dimensões e métricas específicas de coortes, leia dimensões e métricas de valor da vida útil (LTV) e coortes.

Para definir uma solicitação de coorte, é necessário definir um objeto cohort com name, type e dateRange:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions":
      [
        {
          "name": "ga:cohort"
        },
        {
          "name": "ga:cohortNthDay"
        }
      ],
      "metrics":
      [
        {
          "expression": "ga:cohortActiveUsers"
        },
        {
          "expression": "ga:cohortTotalUsers"
        }
      ],
      "cohortGroup":
      {
        "cohorts":
        [
          {
            "name": "cohort 1",
            "type": "FIRST_VISIT_DATE",
            "dateRange":
            {
              "startDate": "2015-08-01",
              "endDate": "2015-08-01"
            }
          },
          {
            "name": "cohort 2",
            "type": "FIRST_VISIT_DATE",
            "dateRange":
            {
              "startDate": "2015-07-01",
              "endDate": "2015-07-01"
            }
          }
        ]
      }
    }
  ]
}

Veja o exemplo acima no Explorador de APIs.

Restrições de coorte

Para ser válida, uma solicitação de coorte precisa atender às seguintes restrições:

  • A dimensão ga:cohort será incluída se e somente se a solicitação tiver um ou mais definições de coorte.
  • É necessário que o nome do coorte seja único.
  • O número máximo de coortes em uma solicitação é 12.
  • Se ga:cohortNthWeek for definido, a data de início precisará ser domingo, e a data de término, sábado. Se ga:cohortNthMonth for definido, a data de início precisará ser o primeiro dia do mês, e a data de término, o último dia do mês. Se ga:cohortNthDay for definido, o período precisa ser exatamente um dia.
  • Solicitações de coorte com a data de hoje não são permitidas.
  • Solicitações de coorte não devem estar na mesma solicitação batchGet com outro tipo de solicitação.
  • O período em coortes precisa ser subsequente ao dia 01 de fevereiro de 2015.

Valor da vida útil (LTV)

O Relatório de valor da vida útil (LTV, na sigla em inglês) mostra a evolução do valor do usuário (receita) e do engajamento (visualizações do aplicativo, conclusões de meta, sessões e duração da sessão) durante os 90 dias após a aquisição de um usuário. Veja dimensões e métricas específicas de LTV.

Uma solicitação de LTV é definida como um coorte com o campo lifetimeValue definido como true. Por exemplo:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions":
      [
        {
          "name": "ga:cohort"
        },
        {
          "name": "ga:cohortNthWeek"
        }
      ],
      "metrics":
      [
        {
          "expression": "ga:cohortTotalUsersWithLifetimeCriteria"
        },
        {
          "expression": "ga:cohortRevenuePerUser"
        }
      ],
      "cohortGroup":
      {
        "cohorts":
        [
          {
            "name": "cohort 1",
            "type": "FIRST_VISIT_DATE",
            "dateRange":
            {
              "startDate": "2015-08-01",
              "endDate": "2015-09-01"
            }
          },
          {
            "name": "cohort 2",
            "type": "FIRST_VISIT_DATE",
            "dateRange":
            {
              "startDate": "2015-07-01",
              "endDate": "2015-08-01"
            }
          }
        ],
        "lifetimeValue": true
      }
    }
  ]
}

Veja o exemplo acima no Explorador de APIs.

Dimensões e métricas de valor da vida útil (LTV) e coorte

Dimensões

Nome da dimensão Definição
ga:cohort Nome do coorte a que um usuário pertence. Dependendo de como os coortes são definidos, um usuário pode pertencer a vários deles, assim como ele pode pertencer a vários segmentos.
ga:cohortNthDay Ajuste de dia com base no valor zero relativo à data de definição do coorte. Por exemplo, se um coorte for definido com a primeira data de acesso como 2015-09-01, o valor ga:cohortNthDay para a data 2015-09-04 será três.
ga:cohortNthMonth Ajuste de mês com base no valor zero relativo à data de definição do coorte.
ga:cohortNthWeek Ajuste de semana com base no valor zero relativo à data de definição do coorte.
ga:acquisitionTrafficChannel Canal de tráfego pelo qual o usuário foi adquirido. Ele é extraído da primeira sessão do usuário. O canal de tráfego é computado com base nas regras padrão de agrupamento de canal (no nível da vista, se disponível) no momento da aquisição do usuário.
ga:acquisitionSource A origem pela qual o usuário foi adquirido. Derivada da primeira sessão do usuário.
ga:acquisitionMedium A mídia pela qual o usuário foi adquirido. Derivada da primeira sessão do usuário.
ga:acquisitionSourceMedium O valor combinado de ga:userAcquisitionSource e ga:acquisitionMedium.
ga:acquisitionCampaign A campanha pela qual o usuário foi adquirido. Derivada da primeira sessão do usuário.

Métricas

Nome da métrica Definição
ga:cohortActiveUsers Essa métrica é relevante no contexto das dimensões de ajuste com base no valor zero (ga:cohortNthDay, ga:cohortNthWeek ou ga:cohortNthMonth). Ela indica o número de usuários no coorte que estão ativos no período que corresponde ao enésimo dia/semana/mês do coorte. Por exemplo, para ga:cohortNthWeek = 1, que é o número de usuários (no coorte) que estão ativos na segunda semana. Se uma solicitação não tiver ga:cohortNthDay, ga:cohortNthWeek ou ga:cohortNthMonth, essa métrica terá o mesmo valor que ga:cohortTotalUsers.
ga:cohortTotalUsers Número de usuários de um coorte, também conhecido como tamanho do coorte.
ga:cohortAppviewsPerUser Vistas de aplicativos por usuário em um coorte.
ga:cohortGoalCompletionsPerUser Conclusões de meta por usuário em um coorte.
ga:cohortPageviewsPerUser Exibições de página por usuário em um coorte.
ga:cohortRetentionRate Taxa de retenção do coorte.
ga:cohortRevenuePerUser Receita por usuário em um coorte.
ga:cohortVisitDurationPerUser Duração de sessão por usuário em um coorte.
ga:cohortSessionsPerUser Sessões por usuário em um coorte.

Métricas de valor da vida útil (LTV)

Nome da métrica Definição
ga:cohortTotalUsersWithLifetimeCriteria Essa métrica é relevante no contexto de uma solicitação com as dimensões ga:acquisitionTrafficChannel, ga:acquisitionSource, ga:acquisitionMedium ou ga:acquisitionCampaign. Ela representa o número de usuários nos coortes que foram adquiridos por meio do canal, da origem, da mídia e da campanha atuais. Por exemplo, para ga:acquisitionTrafficChannel=Direct, ela representa o número de usuários no coorte que foram adquiridos diretamente. Se nenhuma das dimensões mencionadas estiver presente, o valor dessa métrica será igual a ga:cohortTotalUsers (somente para vistas de aplicativos).
ga:cohortAppviewsPerUserWithLifetimeCriteria Vistas de aplicativos por usuário para a dimensão de aquisição em um coorte (somente para vistas de aplicativos).
ga:cohortGoalCompletionsPerUserWithLifetimeCriteria Conclusão de metas por usuário para a dimensão de aquisição em um coorte (somente para vistas de aplicativos).
ga:cohortPageviewsPerUserWithLifetimeCriteria Exibições de página por usuário para a dimensão de aquisição em um coorte (somente para vistas de aplicativos).
ga:cohortRevenuePerUserWithLifetimeCriteria Receita por usuário para a dimensão de aquisição em um coorte (somente para vistas de aplicativos).
ga:cohortSessionsPerUserWithLifetimeCriteria Duração da sessão por usuário para a dimensão de aquisição em um coorte (somente para vistas de aplicativos).