Integración de transmisión de eventos

Se necesita ayuda del desarrollador

Necesitará la ayuda de su equipo de desarrollo para configurar la integración. Por favor, comparta esta guía con ellos.

Resumen de la integración

Tipo de integración

Fuente: Los datos se envían desde Pushwoosh a su sistema a través de HTTP o gRPC según los activadores de eventos configurados.

¿Cómo funciona la integración?

Pushwoosh transmite datos de eventos de comunicación (p. ej., actividad de push/email) a un endpoint definido por el cliente. Los datos se envían en flujos por lotes a intervalos programados o al alcanzar un tamaño mínimo de lote.

Los datos solo se envían si coinciden con los eventos, plataformas y filtros opcionales seleccionados (códigos de campaña/mensaje, live activity). El endpoint del cliente debe estar listo para recibir y, opcionalmente, responder con un estado.

Glosario

URL del endpoint: Endpoint del lado del servidor que permite recibir solicitudes. El cliente puede especificar un puerto si es necesario.

Ejemplos:

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook_endpoint

Lista de entidades sincronizadas

• Eventos de estadísticas de comunicación (p. ej., Push Enviado, Email Entregado)
• Post events: eventos que su aplicación envía a Pushwoosh a través de postEvent, transmitidos por separado de los eventos de estadísticas de comunicación

Casos de uso

• Seguimiento de la interacción en tiempo real

Supervise las interacciones de los usuarios, como el envío de un push, la apertura de un email o la entrega de un mensaje, a medida que ocurren, lo que permite una visibilidad inmediata del rendimiento de la campaña.

• Integración con análisis externos

Transmita eventos a plataformas de análisis de terceros para la generación de informes y análisis centralizados.

• Flujos de trabajo de usuario automatizados

Active acciones en sistemas externos (como CRM o herramientas de automatización de marketing) basadas en el comportamiento del usuario, p. ej., enviar un mensaje de seguimiento cuando un usuario abre un email.

• Sincronización de la lista de dispositivos

Elimine dispositivos de su propia base de datos cuando ya no puedan recibir mensajes. Consulte Sincronizar los dispositivos dados de baja con su sistema.

Configuración de la integración

Para configurar la integración:

1. En su cuenta de Pushwoosh, vaya a Configuración > Integraciones de terceros, busque Integración de transmisión de eventos y haga clic en Configurar.

2. En la ventana que se abre, complete los campos necesarios.

Introducir la URL del endpoint

En el campo URL del endpoint, introduzca la URL completa a la que se enviarán los eventos, incluyendo el protocolo y el puerto si procede.

Ejemplo

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook\_endpoint

Seleccionar eventos

En el menú desplegable Eventos, seleccione al menos un evento. Si no se selecciona ninguno, la validación fallará. La lista de eventos es gestionada por el backend y puede cambiar con el tiempo.

Proporcionar credenciales de autorización

Si su servidor lo requiere, introduzca el valor completo para la cabecera Authorization en el campo Autorización.

Ejemplos:

• Bearer your_token_here

• Basic base64encoded_credentials

Nota

El valor se inserta tal cual en la cabecera Authorization (HTTP) o en los metadatos de gRPC. Asegúrese de que haya un espacio entre el esquema de autenticación y el token.

Elegir el tipo de transporte

En el menú desplegable Tipo de transporte, elija el protocolo de entrega para la transmisión de eventos: HTTP o gRPC. Cada uno tiene un comportamiento y una configuración específicos.

HTTP

Con el tipo de transporte HTTP, Pushwoosh envía datos en lotes basándose en una de las siguientes condiciones:

• Al menos 100 eventos están listos para ser enviados, o

• Ha pasado una hora desde la última transmisión.

Después de enviar los datos, la conexión se cierra una vez que se recibe una respuesta exitosa.

Si el servidor responde con un error 5xx, Pushwoosh reintentará la solicitud de acuerdo con la política de reintentos definida.

Mecanismo de reintento

Intento	Retraso
1º	1 segundo
2º	3 segundos después del 1er intento
3º	8 segundos después del 2º intento

Si todos los reintentos fallan, la solicitud se descarta.

Tiempo de espera

El tiempo de espera predeterminado para una solicitud es de 30 segundos. Esto se puede personalizar a petición a través del soporte.

Ver ejemplo

gRPC

El tipo de transporte gRPC utiliza transmisión bidireccional para la transmisión de datos. Obtenga más información en la documentación de gRPC.

Se abre una transmisión cuando se cumple una de las siguientes condiciones:

• Al menos 1.000 eventos están listos para su entrega
• Ha pasado una hora desde que se abrió la última transmisión

La transmisión se cierra después de que se envían los eventos. Esto asegura que no se abra una nueva transmisión para cada evento individual en un corto período de tiempo.

Ver especificación de protobuf

Mecanismo de reintento
Cada evento incluye un uuid único. Si un evento falla:

1. La respuesta debe incluir un status distinto de "Success"
2. Se debe incluir el uuid original de la solicitud

Pushwoosh reintentará la entrega basándose en esta respuesta.

Configuración de la conexión

Las opciones avanzadas como TLS, keep-alive o políticas de reintento se configuran manualmente a través del soporte y pueden requerir la participación del equipo de desarrollo.

Habilitar post events

Este interruptor está desactivado por defecto, por lo que solo se transmiten los eventos de estadísticas de comunicación. Para transmitir también los eventos que su aplicación envía a Pushwoosh a través de postEvent, active el interruptor Permitir post events.

En el campo Post events que aparece, seleccione cuáles de los eventos de su cuenta desea transmitir. Se requiere al menos un evento mientras el interruptor está activado. Si su cuenta aún no ha enviado ningún evento, esta lista estará vacía hasta que llame a postEvent al menos una vez.

Nota

Los post events se envían a la misma URL del endpoint introducida anteriormente, y llegan a ella independientemente de la plataforma: las secciones Plataformas y Filtros avanzados que se describen a continuación se aplican únicamente a los eventos de estadísticas de comunicación, no a los post events.

Las impresiones y los clics de in-app también se transmiten a través de este flujo de post events, como PW_InAppShow y PW_InAppClicked. Cada uno aparece en la lista Post events solo después de haberse activado al menos una vez para la cuenta, igual que cualquier otro post event.

Seleccionar plataformas

En la sección Plataformas, seleccione al menos una plataforma para activar la transmisión de eventos.

Las plataformas compatibles incluyen:

• iOS, Android, macOS, Windows, Amazon, Safari
• Chrome, Firefox, Internet Explorer, Huawei
• Email, SMS, Line, Xiaomi, WhatsApp

Configurar filtros avanzados

En la sección Filtros avanzados, refine los criterios de entrega de eventos utilizando filtros:

• Eventos de live activity: Habilite para recibir eventos de live activity. Estos eventos contienen solo metadatos que incluyen live_activity_id.

• Filtros de campaña: Filtre por código de campaña. Solo se entregarán los eventos vinculados a estas campañas.

• Filtros de mensaje: Filtre por código de mensaje. Solo se entregarán los eventos vinculados a estos mensajes.

Después de completar todos los campos requeridos, haga clic en el botón Aplicar para guardar y activar su integración.

Nota

Los cambios de configuración entrarán en vigor en un plazo de 15 minutos después de su envío.

Consejo

Para configuraciones avanzadas como tiempos de espera personalizados o configuraciones de gRPC, por favor contacte con soporte.

Detalles y ejemplo de la solicitud

Endpoint	https://exampleclientendpoint.com/webhook_endpoint
Solicitud HTTP	POST
Autenticación	No
Tipo de solicitud	Fuente
Significado de la solicitud	Enviar solicitudes al endpoint del webhook
Cabeceras	Content-Type: application/json

Ejemplo de cuerpo de la solicitud

{
  "event_name": "Email Opened",
  "message_code": "E682-E6D92B9A-53E24868",
  "campaign_id": 961048,
  "platform": "Email",
  "payload": "Welcome to Headway! 👋",
  "application_code": "XXXXX-XXXXX",
  "hwid": "user@example.com",
  "user_id": "USER_ID",
  "timestamp": 1723799271,
  "journey_title": "",
  "journey_point_title": "5_Welcome_ID_new",
  "attributes": null
}

Atributos

Entre los eventos de estadísticas de comunicación, attributes solo se rellena para los eventos de push, con contenido específico del canal (Android, iOS, etc.) para la plataforma a la que se envió el push. Los eventos de Email y SMS solo llevan los campos de nivel superior (event_name, platform, payload, etc.). attributes es null para esos eventos. Dentro de un objeto attributes rellenado, los campos fuera de la propia plataforma del evento se omiten en lugar de enviarse como valores vacíos. Consulte webhook.proto para ver la lista completa de campos.

Un post event lleva sus pares de clave/valor de atributo en attributes.event_attributes. message_code y payload permanecen vacíos, porque un post event no está vinculado a un mensaje o campaña.

Precaución

attributes.geozone está obsoleto: la propiedad de origen es un objeto, no un número, por lo que este campo nunca tuvo un valor real. Lea la geozona real de attributes.geozone_data. El campo antiguo permanece en el contrato para los clientes con stubs gRPC existentes.

Respuesta
Por el momento, el código de respuesta y el cuerpo se ignoran.

Sincronizar los dispositivos dados de baja con su sistema

Si mantiene su propia copia de la lista de dispositivos, por ejemplo en un CRM o en una plataforma de datos de clientes, transmita el post event PW_DeviceUnregistered para encontrar los dispositivos a los que Pushwoosh ya no puede llegar. Pushwoosh envía este evento cuando un dispositivo pierde su suscripción push: el servicio push informa de que el token no es válido, la aplicación da de baja el dispositivo a través del SDK o el usuario se da de baja de los emails.

Parta de una integración que ya esté configurada, con una URL del endpoint introducida y al menos una plataforma seleccionada. Después:

1. En la configuración de la integración, active Permitir post events. Consulte Habilitar post events.
2. En el campo Post events, seleccione PW_DeviceUnregistered.
3. Para saber también qué dispositivos obtienen un token de push, seleccione PW_DeviceRegistered.
4. Haga clic en Aplicar. El cambio entra en vigor en un plazo de 15 minutos.

PW_DeviceUnregistered aparece en la lista Post events solo después de haberse activado al menos una vez para la cuenta. Hasta entonces, no puede seleccionarlo.

Tenga en cuenta estas limitaciones al procesar los eventos:

• Identifique los dispositivos por hwid o user_id, no por el token de push. El evento incluye el hwid, el user_id y la plataforma del dispositivo, pero no el token de push ni el motivo de la baja. Un token caducado y una baja a través del SDK se ven igual.
• La rotación del token no envía ningún evento. PW_DeviceRegistered se activa solo cuando un dispositivo sin token de push recibe uno. Cuando un dispositivo sustituye su token por uno nuevo, no se activa ninguno de los dos eventos, por lo que una lista basada en tokens sigue acumulando tokens obsoletos.
• La baja de los emails no elimina el dispositivo. En el caso del email, la dirección permanece en el dispositivo y Pushwoosh solo la marca como dada de baja. Si el usuario se dio de baja mediante un enlace de un email, attributes.event_attributes también incluye el message_code y el campaign_id de ese email.

Como un lote que agota todos los reintentos HTTP se descarta, es posible que algunos eventos nunca lleguen a su endpoint. Concilie su lista periódicamente: exporte el segmento de los dispositivos a los que se dirige a CSV y compárelo con sus registros. Para exportar un segmento, su rol necesita el permiso Personal data.

¿Cómo saber si la integración está funcionando?

Comenzará a recibir solicitudes de Pushwoosh en su endpoint configurado.