Listas de público-alvo recorrentes

Neste documento, descrevemos as listas de público-alvo recorrentes, que são um recurso avançado da API Google Analytics Data v1. Para uma introdução ao recurso de exportação de lista de público-alvo, consulte o guia básico de exportação de público-alvo.

As listas de público-alvo recorrentes produzem listas de público-alvo diariamente à medida que as associações de público-alvo mudam, para garantir que você trabalhe com os dados mais recentes.

As listas de público-alvo regulares (não recorrentes) são listas estáticas de usuários no público-alvo no momento em que a lista é gerada.

Criar uma nova lista de público-alvo diariamente

O tempo necessário para processar os dados do público-alvo de um dia e atualizar a associação é variável. Não é possível garantir que os dados da lista de público-alvo sejam atualizados em 24 horas.

Por exemplo, mesmo que você solicite uma lista de público-alvo no mesmo horário todos os dias, em alguns dias ela será igual ao dia anterior e, em outros, ela será diferente e terá mais um dia de alterações nas associações.

As listas de público-alvo são baseadas em dados de eventos de um dia antes das mudanças mais recentes na associação. Se você criar uma lista de público-alvo antes das atualizações diárias da associação, ela usará dados dos dois dias anteriores. Se você criar uma lista de público-alvo após as atualizações diárias da assinatura, ela usará dados de ontem.

Pesquisar periodicamente uma lista de público-alvo recorrente

As listas de público-alvo recorrentes só produzem listas de público-alvo quando dados de um dia extra estão disponíveis. Isso elimina o trabalho de decidir quando criar novas listas de público-alvo. Em vez disso, você pode pesquisar de maneira econômica a lista de público-alvo recorrente ao longo do dia para ver se há dados adicionais disponíveis.

Criar uma lista de público-alvo recorrente

Para criar uma lista de público-alvo recorrente, chame o método recurringAudienceLists.create usando o objeto RecurringAudienceList 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 pode ser encontrada na documentação Esquema de exportação de público-alvo. Somente os dados das dimensões mencionadas nesse campo são incluídos em uma lista de público-alvo.

Este é um exemplo de solicitação de criação de lista de público-alvo recorrente:

Solicitação HTTP

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

Uma resposta do método recurringAudienceLists.create contém o nome no campo name (como properties/1234567/recurringAudienceLists/123), que pode ser usado em consultas subsequentes para recuperar os metadados de configuração para essa lista de público-alvo recorrente. Além disso, os metadados de configuração contêm nomes de recursos para instâncias de listas de público-alvo criados para essa lista de público-alvo recorrente.

Resposta HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

Pesquisar metadados de configuração

Use o método recurringAudienceLists.get para recuperar metadados de configuração sobre uma lista de público-alvo recorrente específica. Os metadados de configuração contêm nomes de recursos para instâncias de listas de público-alvo criados para essa lista de público-alvo recorrente.

Veja um exemplo:

Solicitação HTTP

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists/123

Uma instância de RecurringAudienceList é retornada em resposta. Ele contém os metadados de configuração, que incluem nomes de recursos para instâncias de listas de público-alvo criados para essa lista de público-alvo recorrente.

Resposta HTTP

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

Use recurringAudienceLists.list para listar todas as listas de público-alvo recorrentes de uma propriedade.

Usar webhooks para receber notificações assíncronas sobre novas listas de público-alvo

Em vez de consultar periodicamente os metadados de configuração sobre uma lista de público-alvo recorrente específica usando o método recurringAudienceLists.get, é possível receber notificações de webhook de forma assíncrona quando uma lista de público-alvo estiver disponível.

Para configurar notificações de webhook, especifique o campo webhookNotification ao criar uma nova lista de público-alvo recorrente.

Siga o guia Async audience lists with webhooks para mais informações sobre como usar webhooks na API Google Analytics Data v1.

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

Para recuperar usuários em uma exportação de público-alvo, chame o método audienceExports.query e especifique o nome da exportação de público-alvo recuperado dos metadados de configuração fornecidos por recurringAudienceLists.get ou recurringAudienceLists.list.

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
}