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 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 nova lista de público-alvo diariamente

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 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á um dia adicional de mudanças de associaçã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 que as atualizações diárias de associação ocorram, ela usará 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 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 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 saber 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 recurringAudienceLists.create método usando o RecurringAudienceList objeto em uma solicitação. Os seguintes parâmetros são necessários:

  • Um nome de público-alvo válido no audience campo, formatado como properties/{propertyId}/audiences/{audienceId}. Você pode usar o audiences.list método da API Admin do Google Analytics 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 dimensions campo. A lista de dimensões com suporte para 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 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"
  ]
}

Consultar metadados de configuração

Use o recurringAudienceLists.get método 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 na resposta. Ela 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"
  ]
}

Você pode usar 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 recurringAudienceLists.get método, você pode 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 webhookNotification campo ao criar uma nova lista de público-alvo recorrente.

Consulte o Async audience lists with webhooks guia 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 audienceExports.query método 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
}