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 Google Analytics Data API. Para obtener una introducción a la función de exportación de público, consulta cómo crear una exportación de público.

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

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

Para crear una aplicación de webhook de muestra con Google Cloud, sigue 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 que se envía 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 implementa 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 webhookNotification objeto:

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

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

A continuación, se muestra una solicitud de muestra 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 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 muestra un mensaje de error.

Este es un ejemplo de 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 enviada 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 reproducidas.

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 de la falla 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.

A continuación, se muestra un ejemplo de la primera notificación de 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"
      }
  }

A continuación, se muestra un ejemplo de la segunda notificación de 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 audienceLists.query método.

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.