Reciba notificaciones de webhook para sus listas de público

En esta guía, se explica cómo usar webhooks para recibir notificaciones asíncronas sobre el estado de tus solicitudes de exportación de público. Esta función solo está disponible en la versión v1alpha de la API de Data.

Las notificaciones de webhook son una función avanzada de la API de Data de Google Analytics. Para obtener una introducción a la función de exportación de públicos, consulta cómo crear una exportación de público.

Sin webhooks, deberás sondear la API periódicamente para determinar cuándo se completa una solicitud.

Crea una aplicación de webhook de muestra con Cloud Run

Puedes crear una aplicación de webhook de muestra con Google Cloud siguiendo el instructivo Guía de inicio rápido: Implementa un servicio de muestra en Cloud Run.

Para que el servicio de muestra escuche las solicitudes de notificación de webhook POST, reemplaza el archivo index.js del instructivo de inicio rápido por el siguiente código:

  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}`);
  });

Para cada notificación de webhook entrante enviada como una solicitud POST, este código imprime el cuerpo JSON de la notificación de webhook y un valor de token de canal, y devuelve el código HTTP 200 para indicar que la operación se realizó correctamente.

Una vez que llegues al final del instructivo de inicio rápido de Cloud Run y hayas implementado la aplicación de webhook con el comando gcloud run deploy, guarda la URL en la que se implementó tu servicio.

La URL del servicio se muestra en la consola, por ejemplo:

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

Este es el URI de notificación del servidor en el que tu aplicación escucha las notificaciones de webhook de Google Analytics.

Crea una lista de público y activa las notificaciones de webhook

Para solicitar notificaciones de webhook, especifica los siguientes valores en el objeto webhookNotification:

  • El URI de notificación del servidor que contiene la dirección web que recibirá las notificaciones de webhook.

  • (Opcional) Es una cadena arbitraria channelToken para evitar que se suplante el mensaje. Especifica channelToken en el encabezado HTTP X-Goog-Channel-Token de la solicitud POST del webhook.

A continuación, se muestra una solicitud de ejemplo con webhooks:

Solicitud 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 respuesta del método audienceLists.create contiene el objeto webhookNotification, que confirma que el webhook especificado respondió correctamente en menos de 5 segundos.

Esta es una respuesta de ejemplo:

Respuesta 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 no responde o si proporcionas una URL de servicio incorrecta, se devolverá un mensaje de error.

Este es un ejemplo del error que podrías recibir:

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

Procesa notificaciones de webhook

La solicitud POST a un servicio de webhook contiene una versión JSON del recurso de operación de larga duración en el cuerpo y un campo sentTimestamp. La marca de tiempo de envío especifica la hora de la época de Unix en microsegundos en la que se envió la solicitud. Puedes usar esta marca de tiempo para identificar las notificaciones que se volvieron a reproducir.

Se envían una o dos solicitudes POST al webhook durante la creación de una lista de público:

  1. La primera solicitud POST se envía de inmediato y muestra la lista de público recién creada en su estado CREATING. Si falla la primera solicitud al webhook, la operación audienceLists.create devuelve un error y los detalles del error del webhook.
  2. La segunda solicitud POST se envía después de que se completa la creación de la lista de público. La creación se completa cuando la lista de público alcanza el estado ACTIVE o FAILED.

Este es un ejemplo de la primera notificación para una lista de público, en el estado 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"
      }
  }

Este es un ejemplo de la segunda notificación para una lista de público, en el estado 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 segunda notificación confirma que se creó la lista de público y que está lista para consultarse con el método audienceLists.query.

Para probar los webhooks después de llamar al método audienceLists.create, puedes inspeccionar los registros de tu aplicación de webhook de Cloud Run de muestra y ver el cuerpo JSON de cada notificación que envía Google Analytics.