Listes d'audience récurrentes

Ce document décrit les listes d'audience récurrentes, qui sont une fonctionnalité avancée de l'API Google Analytics Data v1. Pour en savoir plus sur la fonctionnalité d'exportation de listes d'audience, consultez le guide sur les principes de base de l'exportation d'audience.

Les listes d'audience récurrentes génèrent des listes d'audience quotidiennement à mesure que les appartenances aux audiences changent, afin de vous assurer que vous travaillez avec les données les plus récentes.

Les listes d'audience standards (non récurrentes) sont des listes statiques d'utilisateurs de l'audience au moment où la liste est générée.

Créer une liste d'audience par jour

Le traitement des données d'audience d'une journée et la mise à jour de l'appartenance prennent un certain temps. Il n'est pas possible de s'assurer que les données de la liste d'audience sont mises à jour dans les 24 heures.

Par exemple, même si vous demandez une liste d'audience à la même heure chaque jour, certains jours, la liste d'audience sera identique à celle de la veille, et d'autres jours, elle sera différente et contiendra un jour supplémentaire de modifications d'appartenance.

Créer une liste d'audience par jour

Les listes d'audience sont basées sur les données d'événement du jour précédant les modifications d'appartenance les plus récentes. Si vous créez une liste d'audience avant les mises à jour quotidiennes de l'appartenance, elle utilisera les données des deux jours précédents. Si vous créez une liste d'audience après les mises à jour quotidiennes des membres, elle utilisera les données de la veille.

Interroger régulièrement une liste d'audience récurrente

Les listes d'audience récurrentes ne génèrent des listes d'audience que lorsque des données d'un jour supplémentaire sont disponibles. Cela vous évite d'avoir à deviner quand créer des listes d'audience. À la place, vous pouvez interroger la liste d'audience récurrente à moindre coût tout au long de la journée pour voir si des données supplémentaires sont disponibles.

Interroger régulièrement une liste d'audience récurrente au cours de la journée

Créer une liste d'audience récurrente

Pour créer une liste d'audience récurrente, appelez la méthode recurringAudienceLists.create à l'aide de l'objet RecurringAudienceList dans une requête. Les paramètres suivants sont requis :

  • Un nom d'audience valide dans le champ audience, au format properties/{propertyId}/audiences/{audienceId}. Vous pouvez utiliser la méthode audiences.list de l'API Google Analytics Admin v1 pour obtenir cette valeur. Le champ Audience.name de la réponse audiences.list contient le nom de l'audience.
  • Une liste valide de dimensions dans le champ dimensions. La liste des dimensions compatibles avec cette méthode est disponible dans la documentation sur le schéma d'exportation d'audience. Seules les données des dimensions mentionnées dans ce champ sont incluses dans une liste d'audience.

Voici un exemple de requête de création de liste d'audience récurrente :

Requête HTTP

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

La réponse de la méthode recurringAudienceLists.create contient le nom dans le champ name (par exemple, properties/1234567/recurringAudienceLists/123), qui peut être utilisé dans les requêtes ultérieures pour récupérer les métadonnées de configuration de cette liste d'audience récurrente. De plus, les métadonnées de configuration contiennent les noms de ressources des instances de liste d'audience créées pour cette liste d'audience récurrente.

Réponse HTTP

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

Métadonnées de configuration du sondage

Utilisez la méthode recurringAudienceLists.get pour récupérer les métadonnées de configuration d'une liste d'audience récurrente spécifique. Les métadonnées de configuration contiennent les noms de ressources des instances de liste d'audience créées pour cette liste d'audience récurrente.

Exemple :

Requête HTTP

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

Une instance de RecurringAudienceList est renvoyée en réponse. Il contient les métadonnées de configuration, qui incluent les noms de ressources des instances de liste d'audience créées pour cette liste d'audience récurrente.

Réponse HTTP

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

Vous pouvez utiliser recurringAudienceLists.list pour lister toutes les listes d'audience récurrentes d'une propriété.

Utiliser des webhooks pour recevoir des notifications asynchrones concernant les nouvelles listes d'audience

Au lieu d'interroger régulièrement les métadonnées de configuration d'une liste d'audience récurrente spécifique à l'aide de la méthode recurringAudienceLists.get, vous pouvez recevoir des notifications de webhook de manière asynchrone lorsqu'une liste d'audience devient disponible.

Pour configurer les notifications Webhook, spécifiez le champ webhookNotification lorsque vous créez une liste d'audience récurrente.

Pour en savoir plus sur l'utilisation des webhooks dans l'API Google Analytics Data v1, consultez le guide Async audience lists with webhooks.

Récupérer les utilisateurs d'une exportation d'audience

Pour récupérer les utilisateurs d'une exportation d'audience, appelez la méthode audienceExports.query et spécifiez le nom de l'exportation d'audience récupéré à partir des métadonnées de configuration fournies par recurringAudienceLists.get ou recurringAudienceLists.list.

Requête HTTP

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

Si l'exportation d'audience est prête, une réponse contenant la liste des utilisateurs d'une audience est renvoyée :

Réponse 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
}