Listes d'audience récurrentes

Ce document décrit les listes d'audience récurrentes, une fonctionnalité avancée de l'API Google Analytics Data v1. Pour une présentation de la fonctionnalité d'exportation de listes d'audience, consultez le guide Principes de base de l'exportation de listes d'audience.

Les listes d'audience récurrentes génèrent des listes d'audience tous les jours à mesure que l'appartenance à l'audience change, 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 chaque jour

Le traitement des données d'audience d'une journée et la mise à jour de l'appartenance prennent un temps variable. Il n'est pas possible de s'assurer que les données de la liste d'audience sont mises à jour en 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 la même que 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 chaque jour

Les listes d'audience sont basées sur les données d'événements de la veille des dernières modifications d'appartenance. Si vous créez une liste d'audience avant que les mises à jour quotidiennes de l'appartenance ne soient effectuées, elle utilisera les données des deux jours précédents. Si vous créez une liste d'audience après que les mises à jour quotidiennes de l'appartenance ont été effectuées, elle utilisera les données de la veille.

Interroger périodiquement une liste d'audience récurrente

Les listes d'audience récurrentes ne génèrent des listes d'audience que lorsque les données d'un jour supplémentaire sont disponibles. Vous n'avez donc plus à deviner quand créer de nouvelles listes d'audience. Vous pouvez plutôt interroger à faible coût la liste d'audience récurrente 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 recurringAudienceLists.create méthode à l'aide de l' RecurringAudienceList objet dans une requête. Les paramètres suivants sont requis :

  • Un nom d'audience valide dans le audience champ, au format properties/{propertyId}/audiences/{audienceId}. Vous pouvez utiliser la audiences.list méthode de l'API Google Analytics Admin v1 pour obtenir cette valeur. Le Audience.name champ de la audiences.list réponse contient le nom de l'audience.
  • Une liste de dimensions valide dans le dimensions champ. La liste des dimensions compatibles avec cette méthode est disponible dans la documentation Schéma d'exportation de listes 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"
    }
  ]
}

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

Interroger les métadonnées de configuration

Utilisez la recurringAudienceLists.get méthode 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. Elle 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 périodiquement les métadonnées de configuration d'une liste d'audience récurrente spécifique à l'aide de la recurringAudienceLists.get méthode, vous pouvez recevoir de manière asynchrone des notifications Webhook lorsqu'une liste d'audience devient disponible.

Pour configurer les notifications Webhook, spécifiez le webhookNotification champ 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 Async audience lists with webhooks guide.

Récupérer les utilisateurs dans une exportation de liste d'audience

Pour récupérer les utilisateurs dans une exportation de liste d'audience, appelez la audienceExports.query méthode et spécifiez le nom de l'exportation de liste 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 de liste 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
}