Esta página foi traduzida pela API Cloud Translation.

Princípios básicos da exportação de público-alvo

Com os públicos-alvo no Google Analytics 4, é possível segmentar os usuários das maneiras mais relevantes para sua empresa. Com os públicos-alvo, você pode agrupar usuários do seu site ou aplicativo com base em atributos compartilhados.

Com a API Data v1 do Google Analytics, você pode gerar exportações de públicos-alvo, que incluem um resumo dos usuários no público-alvo.

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

A API Data v1 do Google Analytics usa uma abordagem assíncrona para criar exportações de público-alvo. Primeiro, é necessário enviar uma solicitação para o método audienceExports.create para criar uma exportação de público-alvo de usuários. Em seguida, o método audienceExports.query é usado para recuperar os usuários no público-alvo.

Além disso, é possível usar audienceExports.get para recuperar 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.

Selecionar uma entidade denunciante

Todos os métodos da API Data v1 exigem que o identificador da propriedade do Google Analytics 4 seja especificado em um caminho de solicitação de URL no formato properties/GA4_PROPERTY_ID, como:

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

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

Se estiver usando uma das bibliotecas de cliente da API Data, não será necessário manipular manualmente o caminho do URL da solicitação. A maioria dos clientes de API fornece um parâmetro property que espera uma string no formato de properties/GA4_PROPERTY_ID. Consulte o Guia de início rápido para exemplos de como usar as bibliotecas de cliente.

Solicitar a criação da 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 em uma 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}. Você pode 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 está na documentação 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.

Exemplo de solicitação de criação da exportação de público-alvo:

Solicitação HTTP

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 (como properties/1234567/audienceExports/123), que pode ser usado em consultas subsequentes para recuperar os usuários da exportação de público-alvo.

Resposta HTTP

{
  "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"
  }
}

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

Pode levar vários minutos para gerar a exportação de público-alvo após a chamada audienceExports.create. Para saber 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 (como properties/1234567/audienceExports/123) que você recebeu de uma resposta audienceExports.create para especificar a exportação.

Exemplo:

Solicitação HTTP

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

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

Resposta HTTP

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

Para ver o estado de todas as exportações de público-alvo, chame o método audienceExports.list.

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

Depois que a exportação de público-alvo criada usando o método audienceExports.create for gerada, chame o método audienceExports.query e especifique o nome da exportação de público-alvo, como properties/1234567/audienceExports/123.

Solicitação HTTP

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

Se a exportação de público-alvo estiver pronta, uma resposta contendo a lista de usuários em um público-alvo será retornada:

Resposta HTTP

{
  "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
}

Expectativas de dados de exportação de público-alvo

A seção a seguir define as expectativas de dados para associações de usuários em exportações de público-alvo.

Atualização de dados

A atualização de dados da exportação de público-alvo é o tempo que o Google Analytics leva para coletar eventos, processá-los e atualizar a associação do usuário nos públicos-alvo. Se esse processo todo levar 24 horas, a atualização de dados da exportação de público-alvo será de 24 horas. Consulte Atualização de dados para saber mais.

Por exemplo, se um usuário concluir a primeira compra e, sete horas depois, você criar uma exportação de público-alvo para o público-alvo "Compradores", ele provavelmente ainda não estará na exportação de público-alvo "Compradores". 14 a 38 horas após a primeira compra, esse usuário provavelmente vai fazer novas exportações de público-alvo.

As exportações de público-alvo são snapshots

As exportações de público-alvo são listas de usuários em um público-alvo em um snapshot no momento. No remarketing do Google Ads, o Analytics exporta usuários em públicos-alvo de forma automática e contínua para o Google Ads. Por outro lado, com as exportações de público-alvo criadas com a API Data v1, você precisa criar uma nova exportação para conferir os usuários mais recentes desse público.

As exportações de público-alvo são criadas com base nas associações mais recentes de usuários disponíveis. No entanto, as exportações de público-alvo podem ter uma atualização de dados de, por exemplo, 20 horas, e isso significa que a exportação de público-alvo será baseada em todos os eventos de 20 horas anteriores ao momento atual.

Os dados mais recentes da assinatura são atualizados uma vez por dia, normalmente durante o dia no fuso horário da propriedade. Isso significa que uma exportação de público-alvo para o mesmo público-alvo às 9h e às 11h provavelmente retornará os mesmos dados, mas uma exportação de público-alvo às 15h pode ser diferente com base na inclusão de dados de um dia adicional.

Validade das exportações de público-alvo

As exportações de público-alvo expiram após 72 horas. Novos usuários podem entrar e sair de um público-alvo a cada dia. Para acessar o snapshot mais recente dos usuários, você precisa criar novas exportações de público-alvo para cada dia.

Limites de usuários da exportação de público-alvo

Quando o tamanho de um público-alvo ou propriedade excede um limite de usuários, as exportações de público-alvo retornam amostras representativas do público-alvo. Esses limites dependem do tipo de propriedade (ou seja, uma propriedade padrão ou do 360) e são aplicados em cada exportação de público-alvo individualmente. Os usuários retornados são aqueles no público-alvo solicitado, e são considerados usuários que podem ou não fazer parte do público-alvo.

Tipo de limite	Limites padrão de propriedade	Limites das propriedades do Google Analytics 360
Máximo de usuários retornados	2 milhões	200 milhões
Máximo de usuários considerados	10 milhões	1 bilhão

Consistência de identidade dos relatórios

A identidade do relatório decide como a duplicação dos usuários é eliminada nos relatórios. As exportações de público-alvo NÃO mudam com base na configuração de identidade do relatório. As exportações de público-alvo sempre identificam os usuários pelo User-ID e pelo ID do dispositivo.

Isso significa que os relatórios sobre um público-alvo podem mostrar mais usuários do que a exportação de público-alvo retorna. Por exemplo, se a identidade do relatório for "Baseada em dispositivo" e o ID do usuário for coletado, a duplicação dos relatórios não vai eliminar a duplicação de usuários com base no ID do usuário, mas as exportações de público-alvo vão eliminar a duplicação com base no ID do usuário.

Consistência da adição retroativa de dados

Quando você cria um público-alvo no Google Analytics e ativa o remarketing do Google Ads, o Google Analytics faz o preenchimento retroativo de dados desse público-alvo no Google Ads com membros adicionados recentemente. No entanto, os relatórios do Google Analytics e as exportações de público-alvo NÃO contêm associações de público-alvo preenchidas. Um usuário vai precisar registrar um evento depois que o público-alvo for criado para relatórios e exportações de público-alvo, para mostrar ao usuário nesse público-alvo.

Por exemplo, se um usuário registrar um evento de compra em 20 de junho e você criar um público-alvo de "compradores" em 21 de junho, é provável que você precise esperar até 22 de junho para encontrar esse usuário nas novas exportações de público-alvo. No entanto, esse usuário só vai fazer parte da exportação de público-alvo se tiver registrado qualquer evento em 21 de junho.