Listas de público-alvo recorrentes

Este documento descreve as listas de público-alvo recorrentes, que são um recurso avançado da API Data v1 do Google Analytics. Para uma introdução ao recurso de exportação de listas de público-alvo, consulte o guia de noções básicas sobre a 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ê esteja trabalhando 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 lista de público-alvo nova todos os dias

O tempo necessário para processar os dados de público-alvo de um dia e atualizar a associação varia. Não há como ter certeza de que os dados da lista de público-alvo são 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 a lista de público-alvo será a mesma do dia anterior, e em outros dias, a lista de público-alvo será diferente e conterá mais um dia de mudanças de associação.

Criar uma nova lista de público-alvo diariamente

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

Consultar periodicamente uma lista de público-alvo recorrente

As listas de público-alvo recorrentes só produzem listas de público-alvo quando os dados de um dia adicional estão disponíveis. Isso elimina a necessidade de decidir quando criar novas listas de público-alvo. Em vez disso, você pode consultar a lista de público-alvo recorrente ao longo do dia para saber se há outros dados disponíveis.

Consultar periodicamente uma lista de público-alvo recorrente durante o dia

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}. Use o método audiences.list da API Admin v1 do Google Analytics para conferir 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 neste campo são incluídos em uma lista de público-alvo.

Confira 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 dessa lista de público-alvo recorrente. Além disso, os metadados de configuração contêm nomes de recursos para instâncias de lista de público-alvo criadas 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"
  ]
}

Metadados de configuração da pesquisa

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 lista de público-alvo criadas 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 lista de público-alvo criadas 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, você pode receber notificações de webhook de forma assíncrona quando uma lista de público-alvo fica disponível.

Para configurar as 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 Data v1 do Google Analytics.

Extrair 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
}