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 agrupa los eventos en un lote y lo envía cuando se cumple cualquiera de las siguientes condiciones:

• Se han recopilado 10 000 eventos, o

• Han pasado 5 minutos desde que se inició el lote.

Un lote se entrega en solicitudes HTTP de hasta 100 eventos o 768 KiB, según el límite que se alcance primero.

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 código de estado 5xx, 408 o 429, Pushwoosh reintenta 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, Pushwoosh conserva los eventos que no se entregaron y vuelve a intentarlo un minuto después. Los eventos que su endpoint ya aceptó no se vuelven a enviar.

Si su endpoint responde con 400, 413 o 422, Pushwoosh divide la solicitud en otras más pequeñas hasta que el evento rechazado se envía solo y, a continuación, descarta ese evento. Cualquier otra respuesta 4xx detiene la entrega del lote: Pushwoosh lo reintenta durante un máximo de 2 horas y luego lo descarta.

Si su endpoint sigue fallando durante 24 horas sin aceptar ningún evento, Pushwoosh pausa la integración. Consulte Integración pausada.

Tiempo de espera

El tiempo de espera predeterminado para una solicitud es de 60 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
El cuerpo de la respuesta se ignora. Con el transporte HTTP, el código de respuesta determina si los eventos cuentan como entregados. Un código 2xx significa que su endpoint los aceptó.

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. Para conocer los motivos, consulte PW_DeviceUnregistered.

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.

Como cualquier post event, PW_DeviceUnregistered aparece en la lista Post events solo después de haberse activado al menos una vez para la cuenta. Consulte Habilitar post events.

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.
• Un token nuevo para el mismo dispositivo no envía ningún evento. PW_DeviceRegistered se activa solo cuando un dispositivo sin token de push recibe uno. Una lista que almacena los dispositivos por token de push conserva tokens que ya no funcionan, porque cuando un dispositivo obtiene un token nuevo, no se activa ninguno de los dos eventos.
• 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.

Es posible que algunos eventos nunca lleguen a su endpoint: un evento que su endpoint rechaza con 400, 413 o 422 se descarta, al igual que un lote que su endpoint sigue rechazando con otro código 4xx durante 2 horas (consulte HTTP). Para detectar estos dispositivos, exporte periódicamente el segmento de los dispositivos a los que se dirige a CSV y compárelo con su lista de dispositivos. Para exportar un segmento, su rol necesita el permiso Personal data. Si su endpoint sigue fallando durante 24 horas, la integración se pausa y los eventos dejan de llegar. Consulte Integración pausada.

Integración pausada

Si las entregas a su endpoint HTTP siguen fallando durante 24 horas y el endpoint no acepta ningún evento durante ese tiempo, Pushwoosh pausa la integración:

• Pushwoosh deja de enviar eventos al endpoint.
• Los eventos pendientes de envío se descartan. Los eventos del período de pausa no se envían más tarde.
• El propietario de la cuenta recibe un email sobre la pausa. La configuración de la integración no muestra la pausa, por lo que este email es el único aviso.

Un evento cuenta como aceptado cuando su endpoint devuelve un código de respuesta 2xx. Los fallos parciales no pausan la integración: cualquier evento aceptado reinicia el conteo de 24 horas. Las integraciones con el transporte gRPC no se pausan.

Para reanudar la transmisión:

1. Asegúrese de que su endpoint esté accesible y devuelva un código de respuesta 2xx.
2. Vaya a Configuración > Integraciones de terceros, busque Integración de transmisión de eventos y haga clic en Configurar.
3. Haga clic en Aplicar. No necesita cambiar ninguna configuración. La transmisión se reanuda en un plazo de 15 minutos.

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

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