Recevoir des notifications Webhook pour vos listes d'audience

Ce guide explique comment utiliser les Webhooks pour recevoir des notifications asynchrones sur l'état de vos demandes d'exportation d'audience. Cette fonctionnalité n'est disponible que dans la version v1alpha de l'API Data.

Les notifications de webhook sont une fonctionnalité avancée de l'API Data de Google Analytics. Pour obtenir une présentation de la fonctionnalité d'exportation d'audience, consultez Créer une exportation d'audience.

Sans les Webhooks, vous devrez interroger régulièrement l'API pour savoir quand une requête est terminée.

Créer un exemple d'application de webhook à l'aide de Cloud Run

Vous pouvez créer un exemple d'application de webhook à l'aide de Google Cloud en suivant le tutoriel Démarrage rapide : déployer un exemple de service sur Cloud Run.

Pour que l'exemple de service écoute les requêtes de notification de webhook POST, remplacez le fichier index.js du tutoriel de démarrage rapide par le code suivant :

  import express from 'express';

  const app = express();
  app.use(express.json());

  app.post('/', (req, res) => {
    const channelToken = req.get('X-Goog-Channel-Token');
    const bodyJson = JSON.stringify(req.body);

    console.log(`channel token: ${channelToken}`);
    console.log(`notification body: ${bodyJson}`);

    res.sendStatus(200);
  });

  const port = parseInt(process.env.PORT) || 8080;
  app.listen(port, () => {
    console.log(`helloworld: listening on port ${port}`);
  });

Pour chaque notification de webhook entrante envoyée sous forme de requête POST, ce code affiche le corps JSON de la notification de webhook et une valeur de jeton de canal, et renvoie le code HTTP 200 pour indiquer que l'opération a réussi.

Une fois que vous avez terminé le tutoriel de démarrage rapide Cloud Run et déployé l'application de webhook à l'aide de la commande gcloud run deploy, enregistrez l'URL où votre service est déployé.

L'URL du service s'affiche dans la console, par exemple :

  Service URL: https://webhooks-test-abcdef-uc.a.run.app

Il s'agit de l'URI de notification du serveur où votre application écoute les notifications de webhook de Google Analytics.

Créer une liste d'audience et activer les notifications de webhook

Pour demander des notifications par webhook, spécifiez les valeurs suivantes dans l'objet webhookNotification :

  • L'URI de notification du serveur contenant l'adresse Web qui recevra les notifications de webhook.

  • (Facultatif) Chaîne arbitraire channelToken pour éviter que le message ne soit usurpé. Spécifiez le channelToken dans l'en-tête HTTP X-Goog-Channel-Token de la requête POST du webhook.

Voici un exemple de requête utilisant des webhooks :

Requête HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/audienceLists
{
  "webhookNotification": {
    "uri": "https://webhooks-test-abcdef-uc.a.run.app",
    "channelToken": "123456"
  },
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

La réponse de la méthode audienceLists.create contient webhookNotification, ce qui confirme que le webhook spécifié a bien répondu en moins de cinq secondes.

Voici un exemple de réponse :

Réponse HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceList",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged": 51,
    "rowCount": 13956,
    "percentageCompleted": 100,
    "webhookNotification": {
      "uri": "https://webhooks-test-abcdef-uc.a.run.app",
      "channelToken": "123456"
    }
  }
}

Si un webhook ne répond pas ou si vous fournissez une URL de service incorrecte, un message d'erreur s'affiche.

Voici un exemple d'erreur que vous pouvez recevoir :

{
  "error": {
    "code": 400,
    "message": "Expected response code of 200 from webhook URI but instead
    '404' was received.",
    "status": "INVALID_ARGUMENT"
  }
}

Traiter les notifications de webhook

La requête POST envoyée à un service de webhook contient à la fois une version JSON de la ressource d'opération de longue durée dans le corps et un champ sentTimestamp. Le code temporel d'envoi spécifie l'heure de l'époque Unix en microsecondes à laquelle la requête a été envoyée. Vous pouvez utiliser ce code temporel pour identifier les notifications rejouées.

Une ou deux requêtes POST sont envoyées au webhook lors de la création d'une liste d'audience :

  1. La première requête POST est envoyée immédiatement, ce qui permet d'afficher la liste d'audience nouvellement créée dans son état CREATING. Si la première requête envoyée au webhook échoue, l'opération audienceLists.create renvoie une erreur et les détails de l'échec du webhook.
  2. La deuxième requête POST est envoyée une fois la liste d'audience créée. La création est terminée lorsque la liste d'audience atteint l'état ACTIVE ou FAILED.

Voici un exemple de la première notification pour une liste d'audience, à l'état CREATING :

  {
    "sentTimestamp":"1718261355692983",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName":"Purchasers",
    "dimensions":[{"dimensionName":"deviceId"}],
    "state":"CREATING",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged":0,
    "rowCount":0,
    "percentageCompleted":0,
    "webhookNotification":
      {
        "uri": "https://webhooks-test-abcdef-uc.a.run.app",
        "channelToken":"123456"
      }
  }

Voici un exemple de la deuxième notification pour une liste d'audience, à l'état ACTIVE :

  {
    "sentTimestamp":"1718261355692983",
    "name": "properties/1234567/audienceLists/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName":"Purchasers",
    "dimensions":[{"dimensionName":"deviceId"}],
    "state":"ACTIVE",
    "beginCreatingTime": "2024-06-10T04:50:09.119726379Z",
    "creationQuotaTokensCharged":68,
    "rowCount":13956,
    "percentageCompleted":100,
    "webhookNotification":
      {
        "uri": "https://webhooks-test-abcdef-uc.a.run.app",
        "channelToken":"123456"
      }
  }

La deuxième notification confirme que la liste d'audience a été créée et qu'elle est prête à être interrogée à l'aide de la méthode audienceLists.query.

Pour tester les webhooks après avoir appelé la méthode audienceLists.create, vous pouvez inspecter les journaux de votre exemple d'application webhook Cloud Run et afficher le corps JSON de chaque notification envoyée par Google Analytics.