Повторяющиеся списки аудитории

В этом документе описываются списки повторяющихся аудиторий, которые являются расширенной функцией API данных Google Analytics версии 1. Введение в функцию экспорта списков аудиторий см. в руководстве по основам экспорта аудиторий .

Списки повторяющихся аудиторий формируются ежедневно по мере изменения состава аудитории, что гарантирует работу с самыми актуальными данными.

Регулярные (неповторяющиеся) списки аудитории — это статические списки пользователей, входящих в аудиторию на момент создания списка.

Ежедневно создавайте новый список аудитории.

Обработка данных об аудитории за один день и обновление состава участников занимает различное количество времени. Нет никакой гарантии, что данные списка аудитории будут обновлены в течение 24 часов.

Например, даже если вы запрашиваете список аудитории в одно и то же время каждый день, в некоторые дни список аудитории будет таким же, как и в предыдущий день, а в другие дни список аудитории будет другим и будет содержать информацию об изменениях в составе аудитории за дополнительный день.

Ежедневное создание нового списка аудитории.

Списки аудитории формируются на основе данных о событиях за один день до последнего изменения состава участников. Если вы создадите список аудитории до ежедневных обновлений состава участников, он будет использовать данные за два предыдущих дня. Если вы создадите список аудитории после ежедневных обновлений состава участников, он будет использовать данные за вчерашний день.

Периодически проводите опрос среди постоянного списка аудитории.

Повторяющиеся списки аудитории создаются только тогда, когда доступны данные за дополнительный день. Это избавляет от необходимости гадать, когда создавать новые списки аудитории. Вместо этого вы можете недорого опрашивать повторяющийся список аудитории в течение дня, чтобы узнать, появились ли дополнительные данные.

Периодически в течение дня проводится опрос постоянно обновляемого списка аудитории.

Создайте список повторяющихся подписчиков.

Для создания списка повторяющихся аудиторий вызовите метод recurringAudienceLists.create , используя объект RecurringAudienceList в запросе. Необходимы следующие параметры:

  • Допустимое имя аудитории в поле audience , отформатированное как properties/{propertyId}/audiences/{audienceId} . Для получения этого значения можно использовать метод audiences.list из Google Analytics Admin API v1. Поле Audience.name в ответе audiences.list содержит имя аудитории.
  • В поле dimensions должен быть указан допустимый список измерений. Список измерений, поддерживаемых этим методом, можно найти в документации по схеме экспорта аудитории . В список аудитории включаются только данные для измерений, указанных в этом поле.

Вот пример запроса на создание списка повторяющихся аудиторий:

HTTP-запрос 

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

В ответе метода recurringAudienceLists.create в поле name содержится имя (например, properties/1234567/recurringAudienceLists/123 ), которое можно использовать в последующих запросах для получения метаданных конфигурации для этого списка повторяющихся аудиторий. Кроме того, метаданные конфигурации содержат имена ресурсов для экземпляров списка аудиторий, созданных для этого списка повторяющихся аудиторий.

HTTP-ответ 

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

метаданные конфигурации опроса

Используйте метод recurringAudienceLists.get для получения метаданных конфигурации конкретного списка повторяющихся аудиторий. Метаданные конфигурации содержат имена ресурсов для экземпляров списка аудиторий, созданных для этого списка.

Вот пример:

HTTP-запрос 

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

В ответе возвращается экземпляр класса RecurringAudienceList . Он содержит метаданные конфигурации, включая имена ресурсов для экземпляров списков аудитории , созданных для этого повторяющегося списка аудитории.

HTTP-ответ 

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

С помощью функции recurringAudienceLists.list можно получить список всех списков повторяющихся аудиторий для определенного ресурса.

Используйте веб-хуки для получения асинхронных уведомлений о новых списках аудитории.

Вместо периодического опроса метаданных конфигурации конкретного списка повторяющихся аудиторий с помощью метода recurringAudienceLists.get , вы можете асинхронно получать уведомления Webhook, когда список аудиторий становится доступен.

Для настройки уведомлений Webhook укажите поле webhookNotification при создании нового списка повторяющихся аудиторий.

Для получения дополнительной информации об использовании веб-хуков в Google Analytics Data API версии 1 следуйте руководству Async audience lists with webhooks .

Получение пользователей при экспорте аудитории.

Чтобы получить список пользователей в экспорте аудитории, вызовите метод audienceExports.query и укажите имя экспорта аудитории, полученное из метаданных конфигурации, предоставленных методами recurringAudienceLists.get или recurringAudienceLists.list .

HTTP-запрос 

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

Если функция экспорта аудитории готова, возвращается ответ, содержащий список пользователей в аудитории:

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
}