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 de conceptos básicos de la exportación de público.

Las listas de público recurrentes producen listas de público a diario a medida que cambian las membresías de 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 usuarios en el público en el momento en que se genera la lista.

Crea una nueva lista de público a diario

Se tarda una cantidad variable de tiempo en procesar los datos de público de un día y actualizar la membresí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 a la misma hora todos los días, algunos días la lista de público será la misma que la del día anterior y, otros días, la lista de público 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 datos de eventos de un día antes de 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 usará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 la membresía, se usarán los datos de ayer.

Sondea 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 la incertidumbre de decidir cuándo crear listas de público nuevas. En su lugar, puedes sondear la lista de público recurrente durante todo el día para ver si hay datos adicionales disponibles.

Sondeo periódico de una lista de público recurrente durante el día

Crea una lista de público recurrente

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

  • Un nombre de público válido en el audience campo, con el formato properties/{propertyId}/audiences/{audienceId}. Puedes usar el audiences.list método de la API de Google Analytics Admin v1 para obtener este valor. El campo Audience.name de la audiences.list respuesta contiene el nombre del público.
  • Una lista válida de dimensiones en el dimensions campo. La lista de dimensiones compatibles con este método se puede encontrar en la documentación Esquema de exportación de público. Solo los datos de las dimensiones mencionadas en este campo se incluyen en una lista de público.

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

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"
  ]
}

Sondea los metadatos de configuración

Usa el recurringAudienceLists.get método 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 la lista 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

Se muestra una instancia de RecurringAudienceList en la respuesta. Contiene los metadatos de configuración, que incluyen 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 notificaciones de webhook de forma asíncrona cuando una lista de público esté disponible.

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

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

Recupera usuarios en una exportación de público

Para recuperar usuarios en una exportación de público, llama al audienceExports.query método 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 muestra una respuesta que contiene la lista de usuarios en 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
}