Cette page a été traduite par l'API Cloud Translation.

Principes de base de l'exportation d'audience

Les audiences dans Google Analytics 4 vous permettent de segmenter les utilisateurs afin de dégager les données importantes pour votre entreprise. Les audiences vous permettent de regrouper les utilisateurs de votre site ou de votre application en fonction d'attributs partagés.

L'API Google Analytics Data v1 vous permet de générer des exportations d'audiences, qui incluent un instantané des utilisateurs de l'audience.

Créer une exportation d'audience

L'API Data de Google Analytics v1 utilise une approche asynchrone pour créer des exportations d'audience. Tout d'abord, vous devez envoyer une requête à la méthode audienceExports.create pour créer une exportation d'audience des utilisateurs. Ensuite, la méthode audienceExports.query permet de récupérer les utilisateurs de l'audience.

En outre, vous pouvez utiliser audienceExports.get pour récupérer les métadonnées de configuration concernant une exportation d'audience spécifique et audienceExports.list pour répertorier toutes les exportations d'audience d'une propriété.

Sélectionner une entité de reporting

Toutes les méthodes de l'API Data v1 nécessitent que l'identifiant de propriété Google Analytics 4 soit spécifié dans un chemin de requête d'URL au format properties/GA4_PROPERTY_ID, par exemple:

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/audienceExports

Il est généré en fonction des données d'événement Google Analytics collectées dans la propriété Google Analytics 4 spécifiée.

Si vous utilisez l'une des bibliothèques clientes des API Data, il n'est pas nécessaire de manipuler manuellement le chemin de l'URL de la requête. La plupart des clients API fournissent un paramètre property qui attend une chaîne au format properties/GA4_PROPERTY_ID. Consultez le guide de démarrage rapide pour obtenir des exemples d'utilisation des bibliothèques clientes.

Demander la création d'une exportation d'audience

Pour créer une exportation d'audience, appelez la méthode audienceExports.create à l'aide de l'objet AudienceExport dans une requête. Les paramètres suivants sont requis :

Nom d'audience valide dans le champ audience, au format properties/{propertyId}/audiences/{audienceId}. Pour obtenir cette valeur, vous pouvez utiliser la méthode audiences.list de l'API Admin de Google Analytics v1. Le champ 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 compatibles avec cette méthode est disponible dans la documentation Schéma d'exportation des audiences. Seules les données des dimensions mentionnées dans ce champ sont incluses dans une exportation d'audience.

Exemple de demande de création d'exportation d'audience:

Requête HTTP

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

Une réponse de la méthode audienceExports.create contient le nom de l'exportation d'audience dans le champ name (par exemple, properties/1234567/audienceExports/123). Vous pourrez l'utiliser dans les requêtes ultérieures pour récupérer les utilisateurs à partir de l'exportation d'audience.

Réponse HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceExport",
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "CREATING",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  }
}

Interroger l'état de préparation de l'exportation d'audience

La génération de l'exportation d'audience peut prendre plusieurs minutes après l'appel audienceExports.create. Pour connaître l'état de préparation d'une exportation d'audience, appelez la méthode audienceExports.get.

Utilisez le nom de l'exportation d'audience (par exemple, properties/1234567/audienceExports/123) que vous avez reçu à partir d'une réponse audienceExports.create pour spécifier l'exportation d'audience.

Exemple :

Requête HTTP

GET https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123

L'état de préparation d'une exportation d'audience est renvoyé dans le champ state d'une réponse. Une fois l'exportation d'audience générée, son état passe de CREATING à ACTIVE.

Réponse HTTP

{
  "name": "properties/1234567/audienceExports/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "state": "CREATING",
  "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
}

Vous pouvez obtenir l'état de toutes les exportations d'audience en appelant la méthode audienceExports.list.

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

Une fois l'exportation d'audience créée à l'aide de la méthode audienceExports.create, appelez la méthode audienceExports.query et spécifiez le nom de l'exportation d'audience (par exemple, properties/1234567/audienceExports/123).

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
}

Attentes concernant les données d'exportation d'audience

La section suivante définit les attentes en termes de données pour les membres des utilisateurs dans les exportations d'audience.

Fraîcheur des données

La fraîcheur des données d'exportation d'audience correspond au temps nécessaire à Google Analytics pour collecter des événements, les traiter, puis mettre à jour l'appartenance des utilisateurs aux audiences. Si ce processus prend 24 heures, la fraîcheur des données d'exportation d'audience est de 24 heures. Pour en savoir plus, consultez la section Fraîcheur des données.

Par exemple, si un utilisateur effectue son premier achat, puis sept heures plus tard, vous créez une exportation d'audience pour l'audience "Acheteurs". Il est fort probable qu'il ne se trouve pas encore dans l'exportation d'audience "Acheteurs". Dans les 14 à 38 heures suivant le premier achat, cet utilisateur figurera probablement dans de nouvelles exportations d'audience.

Les exportations d'audience sont des instantanés

Les exportations d'audience sont des listes d'utilisateurs d'une audience à un moment donné. Pour le remarketing Google Ads, Google Analytics exporte automatiquement et en continu les utilisateurs dans les audiences vers Google Ads. En revanche, avec les exportations d'audience créées à l'aide de l'API Data v1, vous devez créer une exportation d'audience pour afficher les derniers utilisateurs de cette audience.

Les exportations d'audience sont créées en fonction des dernières adhésions disponibles. Toutefois, la fraîcheur des données des exportations d'audience peut être de 20 heures, par exemple, ce qui signifie qu'elles seront basées sur tous les événements survenus 20 heures avant le moment présent.

Les dernières données d'adhésion sont mises à jour une fois par jour, généralement pendant la journée dans le fuseau horaire de la propriété. Cela signifie qu'une exportation d'audience pour la même audience à 9h et 11h renverra probablement les mêmes données, mais une exportation d'audience à 15h peut être différente si vous incluez les données d'un jour supplémentaire.

Expiration des exportations d'audience

Les exportations d'audience expirent au bout de 72 heures. De nouveaux utilisateurs peuvent rejoindre et quitter une audience chaque jour. Pour obtenir le dernier instantané des utilisateurs, vous devez créer des exportations d'audience pour chaque jour.

Limites d'utilisateurs pour les exportations d'audience

Lorsque la taille d'une audience ou d'une propriété dépasse une limite utilisateur, les exportations d'audience renvoient des échantillons représentatifs de cette audience. Ces limites dépendent du type de propriété (standard ou 360) et sont appliquées individuellement à chaque exportation d'audience. Les utilisateurs connus sont des utilisateurs de l'audience demandée, et les utilisateurs considérés comme étant des utilisateurs qui peuvent ou non être membres de l'audience.

Type de limite	Limites des propriétés standards	Limites des propriétés Analytics 360
Nombre maximal d'utilisateurs renvoyés	2 millions	200 millions
Nombre maximal d'utilisateurs pris en compte	10 millions	1 milliard

Cohérence de l'identité de reporting

L'identité pour le reporting détermine la manière dont les utilisateurs sont dédupliqués dans les rapports. Les exportations d'audience ne changent PAS en fonction du paramètre d'identité pour le reporting. Les exportations d'audiences identifient toujours les utilisateurs par ID utilisateur, puis par ID d'appareil.

Cela signifie que les rapports sur une audience peuvent afficher plus d'utilisateurs que n'en renvoie l'exportation d'audience. Par exemple, si l'identité de reporting est "Basée sur l'appareil" et que l'ID utilisateur est collecté, les rapports ne dédupliqueront pas les utilisateurs en fonction de l'ID utilisateur, mais les exportations d'audience seront dédupliquées en fonction de l'ID utilisateur.

Cohérence du remplissage

Lorsque vous créez une audience dans Google Analytics et activez le remarketing Google Ads, Google Analytics remplit cette audience dans Google Ads avec des membres récemment ajoutés. Toutefois, les rapports Google Analytics et les exportations d'audience ne contiennent PAS les abonnements d'audience de remplissage. Pour l'afficher dans cette audience, un utilisateur doit enregistrer un événement après la création de l'audience dans les rapports et les exportations d'audience.

Par exemple, si un utilisateur enregistre un événement d'achat le 20 juin et que vous créez une audience "Acheteurs" le 21 juin, vous devrez probablement attendre le 22 juin pour voir cet utilisateur dans de nouvelles exportations d'audience. Toutefois, il n'apparaîtra dans l'exportation d'audience que s'il a enregistré un événement le 21 juin.