Listes d'audience récurrentes

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

Les listes d'audience récurrentes génèrent des listes d'audience tous les jours les appartenances aux audiences évoluent, 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 inclus dans l'audience au moment où la liste est générée.

Créer une liste d'audience tous les jours

Le temps nécessaire pour traiter et mettre à jour les données d'audience d'une journée varie . Il n'existe aucun moyen de s'assurer que les données de la liste d'audience sont mises à jour 24 heures.

Par exemple, même si vous demandez une liste d'audience chaque jour à la même heure, certains jours, la liste d'audience que le jour précédent, et les autres jours, la liste d'audience est différente. contenir un jour supplémentaire de changements d'adhésion.

Les listes d'audience sont basées sur les données d'événement enregistrées la veille du jour le plus récent les changements d'adhésion. Si vous créez une liste d'audience avant l'adhésion quotidienne mises à jour, il utilisera les données des deux jours précédents. Si vous créez un liste d'audience après des mises à jour quotidiennes des adhésions, elle utilisera les données hier.

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 lorsqu'un jour si des données sont disponibles. Ainsi, vous n'avez plus à décider quand créer 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 la méthode RecurringAudienceList dans une requête. Les paramètres suivants sont requis :

• Un nom d'audience valide dans audience au format properties/{propertyId}/audiences/{audienceId}. Vous pouvez utiliser audiences.list de la version 1 de l'API Admin de Google Analytics. La 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 acceptées par cette méthode est disponible dans le Documentation sur le schéma d'exportation d'audience. Seules les données associées aux dimensions mentionnées dans ce champ sont incluses dans une liste d'audience.

Voici un exemple de demande récurrente de création de liste d'audience:

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 dans le champ name (par exemple, properties/1234567/recurringAudienceLists/123), qui peut être utilisé dans requêtes ultérieures pour récupérer les métadonnées de configuration pour cette liste d'audience récurrente. De plus, les métadonnées de configuration contiennent Noms de ressources pour les instances de liste d'audience créé 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 du sondage

Utilisez les recurringAudienceLists.get pour récupérer les métadonnées de configuration concernant une une liste d'audience récurrente. Les métadonnées de configuration contiennent Noms de ressources pour les instances de liste d'audience créé 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, qui incluent : Noms de ressources pour les instances de liste d'audience créé 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 afin de 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'audience

Au lieu d'interroger régulièrement les métadonnées de configuration sur un votre liste d'audience récurrente recurringAudienceLists.get , vous pouvez recevoir des notifications Webhook de manière asynchrone lorsqu'une audience est alors disponible.

Pour configurer les notifications Webhook, indiquez le webhookNotification lors de la création d'une liste d'audience récurrente.

Suivez le guide Async audience lists with webhooks pour en savoir plus sur l'utilisation des webhooks dans la version 1 de l'API Google Analytics Data.

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

Pour récupérer les 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ées à 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 dans une audience est renvoyé:

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