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 Google Analytics Data v1. Para uma introdução ao recurso de exportação de lista de público-alvo, consulte o guia de fundamentos da exportação de público-alvo.

As listas de público-alvo recorrentes são geradas diariamente à medida que as associações mudam, garantindo que você trabalhe com os dados mais recentes.

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

Criar uma nova lista de público-alvo todos os dias

Leva um tempo variável para processar os dados de público-alvo de um dia e atualizar a associação. Não há como ter certeza de que os dados da lista de público-alvo serã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 ela será igual à do dia anterior, e em outros, será diferente e vai conter um dia adicional de mudanças na participação.

Criar uma lista de público-alvo por dia

As listas de público-alvo são baseadas em 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 dados dos dois dias anteriores. Se você criar uma lista de público-alvo depois que as atualizações diárias de associação forem feitas, ela vai usar dados de ontem.

Consultar periodicamente uma lista de público-alvo recorrente

As listas de público-alvo recorrentes só são geradas quando há dados de um dia adicional. Isso elimina a necessidade de adivinhar 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 verificar se há mais 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 Google Analytics Admin v1 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 nesse campo são incluídos em uma lista de público-alvo.

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

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 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 lista de público-alvo criadas para essa lista recorrente.

Veja um exemplo:

Solicitação HTTP

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

Uma instância de RecurringAudienceList é retornada na resposta. Ele contém os metadados de configuração, incluindo nomes de recursos para instâncias de lista de público-alvo criadas para essa lista 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 estiver disponível.

Para configurar as notificações de webhook, especifique o campo webhookNotification ao criar uma 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
}