Casos de uso avançado

Este documento descreve vários recursos avançados do Google Analytics API 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 de dados pode criar relatórios em registros personalizados Dimensões e Personalizadas Métricas. A API de metadados Method podem ser usados para listar a API. nomes das Definições personalizadas registradas da sua Propriedade. Esses nomes de API podem ser usadas nas solicitações de relatório método runReport, por exemplo.

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

Dimensões personalizadas no escopo do evento

Etapa 1: consultar o método da API Metadata pelo seu ID da 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ê tem interesse criar relatórios com base na resposta. Se a dimensão não estiver presente, você precisará para 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. O seguinte é 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: consultar o método da API Metadata pelo seu ID da 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ê tem interesse criar relatórios com base na resposta. Se a dimensão não estiver presente, você precisará para 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. O seguinte é 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 no evento

Etapa 1: consultar o método da API Metadata pelo seu ID da 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ê tem interesse criar relatórios com base na resposta. Se a métrica não estiver presente, você precisará registre 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. O seguinte é 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:consultar a API Metadata Method pelo ID da propriedade.

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

Etapa 2:encontre a métrica de taxa de eventos principais de um evento principal do seu interesse na criação de relatórios com base na resposta. Se o evento principal não estiver presente, é preciso configurar a chave evento.

"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. O seguinte é um exemplo de solicitação para o 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: consultar o método da API Metadata pelo seu ID da propriedade.

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

Etapa 2:encontre a média da métrica personalizada no escopo do evento em que você tem interesse criar relatórios com base na resposta. Se a métrica não estiver presente, você precisará registre 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 da métrica personalizada em uma solicitação de relatório. O seguinte é 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 da REST para CohortSpec (link em inglês).

Criar um Relatório de coorte

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

  • A coorte inclui usuários com um firstSessionDate de 2020-12-01. isso é configurado pelo objeto cohorts. Dimensões e métricas do relatório resposta terá como base apenas os usuários da coorte.
  • O Relatório de coorte mostrará três colunas: é configurado pela 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. começando em 2020-12-01 e terminando em 2020-12-06 nesta coorte.
    • Quando uma granularidade de DAILY é usada, a dimensão cohortNthDay é recomendadas para garantir a 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, segue um gráfico para o Relatório de coorte. Um insight neste relatório é que a maior queda no número de usuários ativos dessa coorte é 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 expandir seu site ou app. Coorte os relatórios se concentram na retenção de usuários. Neste exemplo, o relatório mostra essa propriedade melhorou a retenção de usuários de 4 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, o segundo com firstSessionDate de 2020-11-09 e a terceira com um firstSessionDate de 2020-11-16. Como o de usuários na sua propriedade será diferente nesses três dias, compare a métrica de fração de retenção de usuários da coorte de cohortActiveUsers/cohortTotalUsers em vez de usar cohortActiveUsers.

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, segue um gráfico para o Relatório de coorte. Um insight neste relatório é que a retenção de usuários de 4 dias aumentou 10% 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.

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

Coortes semanais e uso de coortes com outros recursos da API

Para remover a variação diária no comportamento do usuário, use as coortes semanais. Na semana relatórios de coorte, todos os usuários com firstSessionDate na mesma semana formam o coorte. As semanas começam no domingo e terminam no sábado. Também neste relatório, dividir a coorte para comparar os usuários com a atividade na Rússia e os usuários com atividade no México. Esse fracionamento usa a dimensão country e uma 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, segue um gráfico do Relatório de coorte. Com base neste essa propriedade está se saindo melhor na retenção de usuários com atividades 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. Você pode defina comparações especificando a classe comparisons em uma definição de relatório. O recurso de comparações da API Data é semelhante até Comparações no front-end do Google Analytics.

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

Criar uma comparação

Você pode criar uma comparação separada para cada conjunto de dados. Por exemplo, para comparar dados do app e da Web, crie uma comparação para Dados de Android e 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 foi chamada "Tráfego do aplicativo" está usando o inListFilter para corresponder a dimensão platform aos valores "iOS" e "Android". A segunda comparação chamada "Tráfego da Web" usa o stringFilter para corresponder ao platform; por "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 é adicionadas automaticamente ao relatório gerado. Este campo contém o nome da comparação fornecida na solicitação.

Veja 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"
        }
      ]
    },

    ...

  ],

...

}