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 des listes d'audience, consultez le guide des principes de base de l'exportation des listes d'audience.
Les listes d'audience récurrentes génèrent des listes d'audience quotidiennement à mesure que les membres de l'audience changent, pour vous permettre de travailler 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 tous les jours
Le traitement des données d'audience d'une journée et la mise à jour de l'adhésion prennent un temps variable. Il n'y a aucun moyen de garantir que 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, elle sera identique à la veille certains jours. D'autres jours, elle sera différente et contiendra un jour supplémentaire de changement d'adhésion.
Les listes d'audience sont basées sur les données d'événement du jour précédant les changements de membres les plus récents. Si vous créez une liste d'audience avant que les mises à jour quotidiennes des membres ne soient mises à jour, les données des deux jours précédents seront utilisées. Si vous créez une liste d'audience après des mises à jour quotidiennes des membres, elle utilisera les données de la veille.
Interroger régulièrement une liste d'audience
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. Ainsi, vous n'avez plus à vous inquiéter de savoir quand créer des listes d'audience. Au lieu de cela, vous pouvez interroger à moindre 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.
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 formatproperties/{propertyId}/audiences/{audienceId}. Pour obtenir cette valeur, vous pouvez utiliser la méthodeaudiences.listde l'API Admin de Google Analytics v1. Le champAudience.namede la réponseaudiences.listcontient 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 Schéma d'exportation des audiences. Seules les données relatives aux 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 ultérieures pour récupérer les métadonnées de configuration pour cette liste d'audience récurrente. En outre, 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.
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 concernant 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 :
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 pour les 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"
]
}
recurringAudienceLists.list vous permet de répertorier toutes les listes d'audience récurrentes d'une propriété.
Utilisez 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 sur 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 de webhook, spécifiez le champ webhookNotification lorsque vous créez une liste d'audience récurrente.
Consultez la documentation WebhookNotification pour en savoir plus sur l'utilisation des webhooks dans l'API Data de Google Analytics v1.
Récupérer les utilisateurs dans une exportation d'audience
Pour récupérer des utilisateurs dans 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
}