Listas de público recurrentes

En este documento, se describen las listas de público recurrentes, que son una función avanzada de la API de Google Analytics Data v1. Para obtener una introducción a la función de exportación de listas de público, consulta la guía básica sobre la exportación de públicos.

Las listas de público recurrentes se generan a diario a medida que cambian las membresías del público para garantizar que trabajes con los datos más recientes.

Las listas de público normales (no recurrentes) son listas estáticas de los usuarios que forman parte del público en el momento en que se genera la lista.

Crea una nueva lista de público todos los días

El tiempo que se tarda en procesar los datos de público de un día y actualizar la membresía varía. No hay forma de asegurarse de que los datos de la lista de público se actualicen en 24 horas.

Por ejemplo, incluso si solicitas una lista de público todos los días a la misma hora, algunos días la lista será igual a la del día anterior y otros días será diferente y contendrá un día adicional de cambios en la membresía.

Crear una nueva lista de público todos los días

Las listas de público se basan en los datos de eventos del día anterior a los cambios de membresía más recientes. Si creas una lista de público antes de que se produzcan las actualizaciones diarias de la membresía, se utilizarán los datos de los dos días anteriores. Si creas una lista de público después de que se produzcan las actualizaciones diarias de membresía, se usarán los datos del día anterior.

Sondea periódicamente una lista de público recurrente

Las listas de público recurrentes solo generan listas de público cuando hay datos de un día adicional disponibles. Esto elimina las conjeturas para decidir cuándo crear nuevas listas de público. En su lugar, puedes sondear la lista de público recurrente de forma económica durante el día para ver si hay datos adicionales disponibles.

Consultar periódicamente una lista de público recurrente durante el día

Cómo crear una lista de público recurrente

Para crear una lista de público recurrente, llama al método recurringAudienceLists.create con el objeto RecurringAudienceList en una solicitud. Se requieren los siguientes parámetros:

  • Es un nombre de público válido en el campo audience, con el formato properties/{propertyId}/audiences/{audienceId}. Puedes usar el método audiences.list de la versión 1 de la API de Google Analytics Admin para obtener este valor. El campo Audience.name de la respuesta audiences.list contiene el nombre del público.
  • Es una lista válida de dimensiones en el campo dimensions. La lista de dimensiones admitidas por este método se puede encontrar en la documentación del Esquema de exportación de públicos. En una lista de público, solo se incluyen los datos de las dimensiones que se mencionan en este campo.

A continuación, se muestra un ejemplo de solicitud de creación de una lista de público recurrente:

Solicitud HTTP

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

Una respuesta del método recurringAudienceLists.create contiene el nombre en el campo name (como properties/1234567/recurringAudienceLists/123), que se puede usar en consultas posteriores para recuperar los metadatos de configuración de esta lista de público recurrente. Además, los metadatos de configuración contienen nombres de recursos para las instancias de la lista de público creadas para esta lista de público recurrente.

Respuesta HTTP

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

Metadatos de configuración de la encuesta

Usa el método recurringAudienceLists.get para recuperar los metadatos de configuración sobre una lista de público recurrente específica. Los metadatos de configuración contienen nombres de recursos para las instancias de listas de público creadas para esta lista de público recurrente.

Por ejemplo:

Solicitud HTTP

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

En la respuesta, se devuelve una instancia de RecurringAudienceList. Contiene los metadatos de configuración, que incluyen los nombres de recursos para las instancias de la lista de público creadas para esta lista de público recurrente.

Respuesta HTTP

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

Puedes usar recurringAudienceLists.list para enumerar todas las listas de público recurrentes de una propiedad.

Usa webhooks para recibir notificaciones asíncronas sobre las listas de público nuevas

En lugar de sondear periódicamente los metadatos de configuración sobre una lista de público recurrente específica con el método recurringAudienceLists.get, puedes recibir de forma asíncrona notificaciones de webhook cuando una lista de público esté disponible.

Para configurar las notificaciones de webhook, especifica el campo webhookNotification cuando crees una lista de público recurrente nueva.

Sigue la guía de Async audience lists with webhooks para obtener más información sobre el uso de Webhooks en la API de Google Analytics Data v1.

Cómo recuperar usuarios en una exportación de público

Para recuperar usuarios en una exportación de público, llama al método audienceExports.query y especifica el nombre de la exportación de público recuperado de los metadatos de configuración proporcionados por recurringAudienceLists.get o recurringAudienceLists.list.

Solicitud HTTP

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

Si la exportación de público está lista, se devuelve una respuesta que contiene la lista de usuarios de un público:

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