Recevoir des notifications Webhook pour vos listes d'audience

Ce guide explique comment utiliser des webhooks pour recevoir des notifications asynchrones concernant l'état de vos requêtes 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 Google Analytics Data. Pour une présentation de la fonctionnalité d'exportation d'audience, consultez Créer une exportation d'audience.

Sans webhooks, vous devrez interroger régulièrement l'API pour déterminer 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 en tant que requête POST, ce code affiche le corps JSON de la notification de webhook et une valeur de jeton de canal, puis 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 de 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 de webhook, spécifiez les valeurs suivantes dans l'webhookNotification objet :

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

  • (Facultatif) Une chaîne arbitraire channelToken pour éviter l'usurpation du message. Spécifiez le channelToken dans l'en-tête HTTP X-Goog-Channel-Token de la requête POST de 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 le webhookNotification, qui confirme que le webhook spécifié a répondu correctement 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 est renvoyé à la place.

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 adressé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 envoyé spécifie l'heure epoch 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, affichant la liste d'audience nouvellement créée dans son état CREATING. Si la première requête adressé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 création de la liste d'audience terminé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 audienceLists.query méthode.

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