Listas de público recurrentes

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

Las listas de público recurrentes producen listas de público a diario a medida que cambian las membresías del público para garantizar que estés trabajando con los datos más recientes.

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

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

Procesar los datos del público de un día y actualizar la membresía tarda una cantidad variable. No hay forma de garantizar que los datos de la lista de público se actualicen en 24 horas.

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

Las listas de público se basan en datos de eventos de un día antes de los cambios más recientes de membresía. Si creas una lista de público antes de que se realicen las actualizaciones de membresía diarias, esta utilizará 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 las membresías, esta usará los datos del día anterior.

Sondear periódicamente una lista de público recurrente

Las listas de público recurrentes solo producen listas de público cuando hay datos de un día adicional disponibles. Esto elimina las conjeturas a la hora de decidir cuándo crear nuevas listas de público. En cambio, puedes consultar la lista de público recurrente a bajo costo durante el día para ver si hay datos adicionales disponibles.

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:

• 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.
• Una lista válida de dimensiones en el campo dimensions. Puedes encontrar la lista de dimensiones compatibles con este método en la documentación Esquema de exportación de públicos. En una lista de público, solo se incluyen los datos de las dimensiones mencionadas en este campo.

Este es un ejemplo de una 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 instancias de listas 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 la configuración de la encuesta

Usa el método recurringAudienceLists.get para recuperar metadatos de configuración sobre una lista de público recurrente específica. Los metadatos de configuración contienen nombres de recursos para 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 respuesta, se muestra una instancia de RecurringAudienceList. Contiene los metadatos de configuración, que incluyen los nombres de recursos para las instancias de listas 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 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 notificaciones de Webhook de forma asíncrona cuando una lista de público esté disponible.

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

Sigue la documentación de WebhookNotification para obtener más información sobre el uso de webhooks en la API de datos de Google Analytics v1.

Recupera 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 exportación de público recuperado de los metadatos de configuración que proporcionan recurringAudienceLists.get o recurringAudienceLists.list.

Solicitud HTTP

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

Si la exportación de públicos está lista, se muestra 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
}