Listes d'audience récurrentes

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

Les listes d'audience récurrentes génèrent des listes d'audience tous les jours à mesure que les membres de l'audience changent. Vous pouvez ainsi travailler avec les données les plus récentes.

Les listes d'audience régulières (non récurrentes) sont des listes statiques d'utilisateurs de l'audience au moment de la génération de la liste.

Créer une liste d'audience quotidienne

Le temps nécessaire pour traiter les données sur l'audience d'une journée et mettre à jour l'appartenance varie. Il n'est pas possible de savoir avec certitude si les données de la liste d'audience sont mises à jour sous 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 du jour précédent, et d'autres jours, elle sera différente et contiendra un jour supplémentaire de modifications d'abonnement.

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

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

Les listes d'audience récurrentes ne produisent des listes d'audience que lorsqu'un jour supplémentaire de données est disponible. Vous n'avez donc plus à deviner quand créer des listes d'audience. Vous pouvez plutôt 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.

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 :

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

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 ultérieures pour récupérer les métadonnées de configuration de cette liste d'audience récurrente. Les métadonnées de configuration contiennent également les noms de ressources pour les instances de liste d'audience créées pour cette liste d'audience récurrente.

{
  "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 des sondages

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 pour les instances de liste d'audience créées pour cette liste d'audience récurrente.

Exemple :

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, y compris les noms de ressources pour les instances de liste d'audience créées pour cette liste d'audience récurrente.

{
  "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 sur les nouvelles listes d'audiences

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 méthode recurringAudienceLists.get, vous pouvez recevoir des notifications Webhook de manière asynchrone lorsqu'une liste d'audience devient disponible.

Pour configurer les notifications par 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 la version 1 de l'API Google Analytics Data, 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.

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:

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