Skip to main content

​
Variables de entorno

Sin API_KEY / APP_ID el cliente degrada a log-only (no lanza) y el health probe reporta el componente como caído.

​
Idempotencia, reintentos y observabilidad

  • Idempotencia: el consumidor usa queue_event_id como queue_event.source_event_id; una reentrega duplicada es un no-op.
  • Reintentos: backoff exponencial en errores transitorios (5xx / red). NonRetryableNotificationError se convierte en un skip registrado sin reintento.
  • Tipos de evento: segmentados por canal (vercel_queue.notification.push|in_app|sms|live_activity, fallback …unified).
  • Contexto de éxito: los handlers devuelven context.oneSignalId para la correlación.

​
Runbook — DLQ y replay

Los fallos que agotan los reintentos aterrizan en la infraestructura compartida de DLQ (queue_dead_letter + queue_replay_job).
1

Detecta

Consulta queue_dead_letter filtrando por event_type LIKE 'vercel_queue.notification.%'.
2

Diagnostica

Revisa queue_event_attempt (último error) y los logs del handler por correlation / queue_event_id.
3

Corrige la causa raíz

Credenciales de OneSignal, número de teléfono o payload.
4

Reprocesa

Encola un queue_replay_job para las filas de queue_event afectadas.
5

Verifica

La fila pasa a processed con context.oneSignalId.
Forzar una API key inválida en dev es la forma más rápida de observar el ciclo reintento → DLQ → replay de extremo a extremo.

​
Salud

Una probe activa barata (GET /apps/{app_id}, sin consumir cuota) combinada con tráfico real pinta el heartbeat INTEGRATION_ONESIGNAL en la página de estado.

​
Checklist de integración móvil

1

Inicializa el SDK

Usa el App ID de OneSignal del entorno.
2

Enlaza al usuario

En la autenticación llama a OneSignal.login(auth.users.id) para establecer el external_id.
3

Renderiza in-app

Maneja el push solo de datos del canal in_app.
4

Registra el teléfono

Persiste el teléfono E.164 del usuario para SMS.
5

Respeta las preferencias

Lee GET /v3/notification/preference/me y persiste los cambios con PUT/PATCH .../me.