@capgo/capacitor-notifications

Resumen

@capgo/capacitor-notifications conecta una app Capacitor con el pipeline de notificaciones nativas de Capgo. Tu app registra un ID de usuario firmado con Capgo, Capgo mantiene el estado del dispositivo activo en el Cloudflare Analytics Engine, y puedes enviar notificaciones, configurar badges, revisar estadísticas de entrega y disparar chequeos silenciosos de Capgo live-update desde el dashboard de Capgo o API.

Esta función evita tener una tabla de dispositivos de alta cardinalidad en el Postgres de Capgo. Postgres solo almacena datos de control de baja cardinalidad como ajustes de la app, metadatos de credenciales, borradores de campañas, horarios y registros agregados. El estado de los dispositivos y los eventos de notificación son filas de solo escritura en el Analytics Engine.

Soporte de plataformas

Plataforma	Soporte	Notas
iOS	Sí	APNs vía Capgo
Android	Sí	FCM mediante Capgo
Web	No	Usa web push por separado

Qué almacena Capgo

Datos	Dónde se ubica	Por qué
Metadatos de credenciales de la plataforma	Capgo Postgres	Necesario para gestionar la configuración y permisos de la app.
Secretos privados de la plataforma	Entorno del Worker	Evita guardar credenciales privadas en tablas expuestas al cliente.
Borradores y ajustes de campañas	Capgo Postgres	Datos de plano de control de baja cardinalidad.
Estado de registro de dispositivos activos	Motor de Cloudflare Analytics	Registro de dispositivos activos append-only y económico.
Eventos de notificación	Motor de Cloudflare Analytics	Estadísticas económicas de eventos en cola, enviados, recibidos, abiertos, fallidos y en segundo plano.

Modelo de Identidad

Capgo no te pide subir una lista de usuarios ni mantener una tabla de dispositivos.

• Tu backend conoce el ID de usuario real del cliente.
• Tu backend solicita a Capgo un token de corta duración identityProof.
• La app se registra con externalId y esa prueba tras completar tu propia autenticación de usuario.
• Capgo genera claves internas deterministas para el destinatario y la instalación nativa.
• Enviar al mismo externalId vuelve a encontrar los dispositivos activos del usuario.

Esto te permite consultar los dispositivos de un usuario, configurar badges y dirigir campañas de notificaciones sin guardar filas de notificaciones por dispositivo en Capgo Postgres.

Funcionalidades principales

• Registra dispositivos con un ID de usuario externo autenticado.
• Actualiza tags, atributos, consentimiento y estado del token al iniciar la app o cuando cambie el token.
• Recibe notificaciones en foreground mediante JavaScript.
• Rastrea los eventos de notificación recibida y abierta.
• Gestiona notificaciones de datos en background.
• Configura, limpia e incrementa los badges de la app.
• Crea canales de notificación en Android.
• Envía notificaciones puntuales, notificaciones de campaña, actualizaciones de badges y comprobaciones de actualización silenciosas.
• Disparador @capgo/capacitor-updater desde una notificación silenciosa.

Estadísticas

Capgo escribe los eventos de notificación en Cloudflare Analytics Engine para que las stats del dashboard sigan siendo económicas:

• queued
• sent
• provider_accepted
• received
• opened
• failed
• permission_changed
• background_started
• background_finished

Las stats son señales operativas, no un registro permanente por destinatario. La retención de Analytics Engine implica que los dispositivos activos deben refrescar su registro periódicamente.

Público API

Método	Descripción
configure	Configura el app ID de Capgo, el host de API y el comportamiento de integración del updater.
register	Registra la instalación actual con un ID de usuario externo.
setExternalId	Cambia el ID de usuario externo tras el login o al cambiar de cuenta.
setTags	Reemplaza las etiquetas usadas para segmentación de audiencia.
setBadge	Establece el badge de la app nativa.
clearBadge	Limpia el badge de la app nativa.
incrementBadge	Incrementa el badge de la app nativa.
enableUpdaterIntegration	Habilita el manejo de silent update-check mediante @capgo/capacitor-updater.
runUpdateCheck	Ejecuta la integración del updater manualmente para pruebas.
trackReceived	Escribe manualmente un evento de recepción.
trackOpened	Escribe manualmente un evento de apertura.
addListener('notificationReceived')	Se dispara cuando se recibe una notificación con JavaScript activo.
addListener('notificationOpened')	Se dispara cuando un usuario abre una notificación.
addListener('backgroundNotification')	Se dispara para notificaciones de datos en background y expone finish().
addListener('registrationChanged')	Se dispara cuando cambia el push token nativo.

Garantías de entrega

El push nativo es de tipo "at-least-once". Una campaña puede reintentarse y un dispositivo puede recibir un duplicado si la plataforma acepta mensajes repetidos. Usa collapse IDs para comprobaciones de actualización y asegúrate de que el trabajo en segundo plano sea idempotente.

Las notificaciones en segundo plano de iOS son "best-effort". El SO puede limitar o saltarse la ejecución en segundo plano según la batería, el comportamiento del usuario, el estado de cierre forzado y las políticas del sistema. No confíes en las notificaciones silenciosas para plazos críticos.

Continúa desde @capgo/capacitor-notifications

Si estás usando @capgo/capacitor-notifications para planificar el envío de mensajes push, conéctalo con Primeros pasos for setup, Depuración para solucionar problemas, @capgo/capacitor-updater para comprobaciones silenciosas de actualización, y Directorio de plugins de Capgo para otros plugins nativos.