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 découvrir 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 sont générées quotidiennement à mesure que les membres de l'audience changent, afin de vous assurer de travailler avec les données les plus récentes.

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

Créer une liste d'audience chaque jour

Le temps nécessaire au traitement des données d'audience d'une journée et à la mise à jour des abonnements est variable. 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, il se peut que certains jours, la liste d'audience soit la même que la veille, et que d'autres jours, elle soit différente et contienne un jour supplémentaire de modifications des membres.

Créer une liste d'audiences chaque jour

Les listes d'audience sont basées sur les données d'événement de la veille des derniers changements de membres. 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 abonnements, 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 sont générées que lorsqu'une journée de données supplémentaire est disponible. Vous n'avez plus besoin de deviner quand créer des listes d'audience. Vous pouvez plutôt interroger à bas prix 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 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 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.
  • 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 demande 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'audiences récurrente. De plus, les métadonnées de configuration contiennent les noms de ressources des instances de listes 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 listes 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 dans la réponse. Il contient les métadonnées de configuration, y compris les noms de ressources pour les instances de listes 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 de manière asynchrone des notifications Webhook 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 l'API Google Analytics Data v1, consultez le guide Async audience lists with webhooks.

Récupérer les utilisateurs dans 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
}