Criar uma exportação de público-alvo

Com os públicos-alvo no Google Analytics, você pode segmentar os usuários de um jeito que seja relevante para sua empresa. Com os públicos-alvo, você pode agrupar usuários do seu site ou aplicativo com base em atributos compartilhados.

É possível exportar seus públicos-alvo, incluindo um resumo dos usuários, usando a API Data.

Consulte o guia Expectativas de dados de exportação de público-alvo para informações importantes sobre os dados exibidos nas exportações de público-alvo.

Visão geral

Faça as seguintes solicitações da API Data para criar e consultar uma exportação de público-alvo:

1. Chame o método audienceExports.create para criar uma exportação de público-alvo.
2. Chame o método audienceExports.query para extrair os usuários do público-alvo.

Para mais informações, chame audienceExports.get para extrair metadados de configuração sobre uma exportação de público-alvo específica e audienceExports.list para listar todas as exportações de público-alvo de uma propriedade específica.

Selecione uma entidade de relatório

Todos os métodos da API Data exigem que o identificador da propriedade do Google Analytics seja especificado em um caminho de solicitação de URL, na forma de properties/GA_PROPERTY_ID. Veja um exemplo:

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/audienceExports

O relatório é gerado com base nos dados de eventos do Google Analytics coletados na propriedade especificada.

Se você estiver usando uma das bibliotecas de cliente da API Data, não será necessário mudar o caminho do URL da solicitação. A maioria dos clientes de API fornece um parâmetro property que deve ser preenchido com uma string no formato properties/GA_PROPERTY_ID. Consulte o guia de início rápido para conferir exemplos de como usar as bibliotecas de cliente.

Criar uma exportação de público-alvo

Para criar uma exportação de público-alvo, chame o método audienceExports.create usando o objeto AudienceExport na sua solicitação. Os seguintes parâmetros são necessários:

• Um nome de público-alvo válido no campo audience, formatado como properties/{propertyId}/audiences/{audienceId}. É possível usar o método audiences.list da API Admin v1 do Google Analytics para receber esse valor. O campo Audience.name da resposta audiences.list contém o nome do público-alvo.
• Uma lista válida de dimensões no campo dimensions. A lista de dimensões compatíveis com esse método pode ser encontrada na documentação do esquema de exportação de público-alvo. Somente os dados das dimensões mencionadas neste campo são incluídos em uma exportação de público-alvo.

Confira um exemplo de solicitação para criar uma exportação de público-alvo:

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

Uma resposta do método audienceExports.create contém o nome da exportação de público-alvo no campo name, por exemplo, properties/1234567/audienceExports/123. Veja um exemplo de resposta:

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceExport",
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "CREATING",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  }
}

Use name para consultar os usuários da exportação de público-alvo.

Consultar o estado de prontidão da exportação do público-alvo

Pode levar vários minutos para gerar a exportação de público-alvo após a chamada audienceExports.create.

Para verificar o estado de prontidão de uma exportação de público-alvo, chame o método audienceExports.get.

Use o nome da exportação de público-alvo de uma resposta audienceExports.create para especificar a exportação de público-alvo na sua solicitação.

Confira um exemplo de solicitação:

GET https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123

O estado de prontidão para uma exportação de público-alvo é retornado no campo state da resposta. Quando a geração da exportação do público-alvo for concluída, o estado dela vai mudar de CREATING para ACTIVE.

Veja um exemplo de resposta:

{
  "name": "properties/1234567/audienceExports/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "state": "CREATING",
  "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
}

É possível conferir o estado de todas as exportações de público-alvo chamando o método audienceExports.list.

Recuperar usuários de uma exportação de público-alvo

Depois que a exportação de público-alvo for gerada, chame o método audienceExports.query e especifique o name da exportação de público-alvo na solicitação.

Confira um exemplo de solicitação:

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

Se a exportação do público-alvo estiver pronta, essa chamada vai retornar a lista de usuários no público-alvo.

Veja um exemplo de resposta:

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}