O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Casos de uso avançado

Este documento descreve vários recursos avançados da API Google Analytics Data v1. 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 personalizadas e métricas personalizadas registradas. O método da API Metadata Metadata Method pode ser usado para listar os nomes de API das definições personalizadas registradas da sua propriedade. Esses nomes de API podem ser usados em solicitações de relatório para o runReport, por exemplo.

As seções a seguir mostram exemplos de cada tipo de definição personalizada. Nestes exemplos, substitua GA_PROPERTY_ID pelo ID da sua propriedade.

Dimensões personalizadas no escopo do evento

Etapa 1: Consulte o método da API Metadata com o ID da sua propriedade.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Etapa 2:encontre a dimensão personalizada no escopo do evento em que você quer criar relatórios na resposta. Se a dimensão não estiver presente, você precisa registrar a dimensão.

"dimensions": [
...
    {
      "apiName": "customEvent:achievement_id",
      "uiName": "Achievement ID",
      "description": "An event scoped custom dimension for your Analytics property."
    },
...
],

Etapa 3:inclua a dimensão personalizada em uma solicitação de relatório. Confira a seguir um exemplo de solicitação para o método runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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 Metadata com o ID da sua propriedade.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Etapa 2:encontre a dimensão personalizada no escopo do usuário em que você quer criar relatórios na resposta. Se a dimensão não estiver presente, você precisa registrar a dimensão.

"dimensions": [
...
    {
      "apiName": "customUser:last_level",
      "uiName": "Last level",
      "description": "A user property for your Analytics property."
    },
...
],

Etapa 3:inclua a dimensão personalizada em uma solicitação de relatório. Confira a seguir um exemplo de solicitação para o método runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "entity": { "propertyId": "GA_PROPERTY_ID" },
  "dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "customUser:last_level" }],
  "metrics": [{ "name": "activeUsers" }]
}

Métricas personalizadas no escopo do evento

Etapa 1: Consulte o método da API Metadata com o ID da sua propriedade.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Etapa 2:encontre a métrica personalizada no escopo do evento em que você quer criar relatórios na resposta. Se a métrica não estiver presente, você precisa registrar a métrica.

"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. Confira a seguir um exemplo de solicitação para o método runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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 Metadata com o ID da sua propriedade.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Etapa 2:encontre a métrica de taxa de eventos principais para um evento principal em que você quer criar relatórios na resposta. Se o evento principal não estiver presente, você precisa configurar o evento principal.

"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 eventos principais em uma solicitação de relatório. Confira a seguir um exemplo de solicitação para o método runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "sessionKeyEventRate:add_to_cart" }]
}

Médias de métricas personalizadas no escopo do evento

Etapa 1: Consulte o método da API Metadata com o ID da sua propriedade.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Etapa 2:encontre a média de métricas personalizadas no escopo do evento em que você quer criar relatórios na resposta. Se a métrica não estiver presente, você precisa registrar a métrica.

"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 de métricas personalizadas em uma solicitação de relatório. Confira a seguir um exemplo de solicitação para o método runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}

Exemplos de relatórios de coorte

Os relatórios de coorte criam uma série temporal de retenção de usuários para a coorte. Para documentação detalhada de cada campo da API, consulte a referência REST para CohortSpec.

Criar um relatório de coorte

Confira um exemplo de relatório de coorte em que:

A coorte é de usuários com uma firstSessionDate de 2020-12-01. Isso é configurado pelo objeto cohorts. 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 vai 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 desde 2020-12-01.
- A métrica cohortActiveUsers é o número de usuários ainda ativos.
O objeto cohortsRange especifica que o relatório precisa conter dados de eventos a partir de 2020-12-01 e terminar em 2020-12-06 para essa coorte.
- Quando uma granularidade de DAILY é usada, a dimensão cohortNthDay é recomendada para consistência.

A solicitação de relatório para a coorte é:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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, um gráfico para esse relatório de coorte é mostrado a seguir. Um insight desse relatório é que a maior queda de usuários ativos para essa coorte ocorre entre o primeiro e o segundo dia.

Visualização dos usuários da coorte ao longo do tempo

Várias coortes e fração de retenção de usuários

A aquisição e a retenção de usuários são maneiras de aumentar 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 uma firstSessionDate de 2020-11-02, a segunda com uma firstSessionDate de 2020-11-09 e a terceira com uma firstSessionDate de 2020-11-16. Como o número de usuários na sua propriedade será diferente para esses três dias, comparamos a métrica de 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/GA_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, um gráfico para esse relatório de coorte é mostrado a seguir. 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 mais recente com firstSessionDate de 2020-11-16 excede a retenção da coorte anterior com firstSessionDate de 2020-11-02.

Gráfico de várias retenções de coorte

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. Além disso, neste relatório, estamos segmentando a coorte para comparar os usuários com atividade na Rússia com usuários com atividade no México. Essa segmentação 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/GA_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, um gráfico desse relatório de coorte é mostrado a seguir. Com base nesse relatório, essa propriedade está tendo um desempenho melhor na retenção de usuários com atividade no México do que usuários com atividade na Rússia.

Gráfico de coortes de comparação de países

Comparações

Com as comparações, você pode avaliar subconjuntos dos seus dados lado a lado. É possível definir comparações especificando o comparisons campo em uma definição de relatório. O recurso de comparações da API Data é semelhante a comparações no front-end do Google Analytics.

Para documentação detalhada de cada campo da API, consulte a referência REST para Comparison.

Criar uma comparação

Você pode criar uma comparação separada para cada conjunto de dados. Por exemplo, se quiser comparar dados do app e da Web, crie uma comparação para os dados do Android e do iOS e outra para os 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 o inListFilter para corresponder à dimensão platform com os valores "iOS" e "Android". A segunda comparação chamada "Tráfego da Web" usa o stringFilter para corresponder à dimensão platform com "web".

  POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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.

Confira um exemplo de snippet 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"
        }
      ]
    },

    ...

  ],

...

}

Casos de uso avançado Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Listar definições personalizadas e criar relatórios

Dimensões personalizadas no escopo do evento

Dimensões personalizadas no escopo do usuário

Métricas personalizadas no escopo do evento

Métricas de taxa de eventos principais para um evento principal

Médias de métricas personalizadas no escopo do evento

Exemplos de relatórios de coorte

Criar um relatório de coorte

Várias coortes e fração de retenção de usuários

Coortes semanais e uso de coortes com outros recursos da API

Comparações

Criar uma comparação

Casos de uso avançado