Depuración

Usa este checklist cuando una notificación no se registra, no llega, no se muestra o no actualiza las estadísticas de Capgo.

Empieza por el registro del dispositivo

Antes de depurar el code nativo, confirma que Capgo puede ver el dispositivo.

1. Abre la app e inicia sesión con el usuario que quieras probar.
2. Llama a CapgoNotifications.register(...) después del inicio de sesión.
3. En Capgo, abre Notificaciones > Búsqueda de destinatarios.
4. Busca por el mismo ID de cliente externo.

Deberías ver al menos un dispositivo activo con:

• recipientKey
• deviceKey
• plataforma android o ios
• estado de permisos
• versión de la app
• versión del plugin
• tags y atributos

Si la búsqueda no devuelve ningún dispositivo, la ruta de envío no puede apuntar a ese usuario.

Añadir listeners de depuración temporales

Añade listeners temporales durante las pruebas. Elimina los logs ruidosos antes de publicar.

await CapgoNotifications.addListener('registrationChanged', (token) => {
  console.log('[CapgoNotifications] registrationChanged', token.value.slice(0, 12))
})

await CapgoNotifications.addListener('notificationReceived', (notification) => {
  console.log('[CapgoNotifications] notificationReceived', notification.id, notification.data)
})

await CapgoNotifications.addListener('notificationOpened', (event) => {
  console.log('[CapgoNotifications] notificationOpened', event.notification.id, event.actionId)
})

await CapgoNotifications.addListener('backgroundNotification', async (event) => {
  console.log('[CapgoNotifications] backgroundNotification', event.notification.id, event.notification.data)
  await event.finish()
})

Recopila esta información

Al depurar con tu equipo o con el soporte de Capgo, recopila:

• ID de la app Capgo.
• ID del paquete de la app o bundle ID de iOS.
• Plataforma del dispositivo y versión del SO.
• Versión de la app y número de build.
• La versión del plugin.
• El ID del cliente externo.
• recipientKey y deviceKey desde el registro o la búsqueda de destinatarios.
• ID de campaña o ID de notificación.
• Si la app estaba en foreground, background, cerrada a la fuerza o recién instalada.
• Los logs del dispositivo de la ejecución que reprodujo el error.

Usa los logs del dispositivo

Mantén un dispositivo real conectado mientras envías una notificación de prueba.

En Android:

• Abre el Logcat de Android Studio.
• Filtra por el ID del paquete de la app.
• Monitorea la solicitud de permisos de notificación, la actualización del token nativo, la recepción de mensajes y los logs del listener de JavaScript.
• Si no aparece una notificación visible, revisa primero la importancia del canal de notificación y el estado de los permisos en Android 13+.

En iOS:

• Ejecuta la app desde Xcode en un dispositivo físico.
• Abre la consola de Xcode o Dispositivos y simuladores logs.
• Filtra por el bundle ID y CapgoNotifications.
• Confirmar AppDelegate.swift reenvía notificaciones remotas y que la capacidad de background mode esté habilitada.

Envía primero una prueba en foreground, luego una en background y después una de silent update-check. Este orden permite distinguir problemas del listener de JavaScript de los límites de entrega en background del OS.

Problemas de registro

La configuración de CLI no se completó

Ejecuta el comando de setup desde la carpeta que contiene capacitor.config.*:

npx @capgo/cli@latest notifications setup com.example.app

Si el comando no puede inferir tu app ID, pásalo explícitamente como se muestra arriba. Si la instalación del paquete falla, confirma que el nombre del paquete sea @capgo/capacitor-notificationscoincida, verifica que tu registro de npm sea https://registry.npmjs.org, comprueba el acceso a la red y vuelve a ejecutar el comando.

El dispositivo no aparece en la búsqueda de destinatarios

Comprobación:

• register se ejecuta después de que tu app tenga un usuario autenticado.
• externalId coincide con el ID de usuario que buscas en el dashboard.
• identityProof fue generado por tu backend para el mismo appId y externalId.
• appId en configure coincide con la app Capgo.
• consent no está configurado en false a menos que el usuario haya optado por no participar.
• El dispositivo tiene acceso de red a https://api.capgo.app.
• Se creó el token de push nativo. Usa registrationChanged para confirmar la renovación del token.

Prueba de identidad no válida

La prueba está vinculada al ID de la app Capgo y al ID externo. Si alguno de los valores cambia, genera una nueva prueba.

No guardes una prueba en caché para siempre ni la reutilices en distintas apps. Genérala desde tu backend tras el login, devuélvela a la app y llama a register.

Dispositivo registrado pero con permiso denegado

El plugin puede registrar el estado del dispositivo incluso si el usuario denegó el permiso. Podrás ver el dispositivo, pero las notificaciones no se mostrarán.

Usa una pantalla previa de permisos antes del prompt del SO. Explica el beneficio para el usuario y pide el permiso solo cuando la acción sea lógica.

Problemas de entrega

En cola pero no enviado

Comprobación:

• El estado de las credenciales de la plataforma es configured en Capgo.
• El entorno del worker contiene la referencia exacta al secret que muestra el dashboard.
• El package ID o bundle ID de la app coincide con la configuración de push de la plataforma.
• La audiencia objetivo resuelve al menos un dispositivo activo.
• La campaña no está limitada a un tag o segmento que el dispositivo no tenga.

Enviada pero no recibida

Comprobación:

• El dispositivo está en línea.
• El usuario no forzó el cierre de la app.
• El permiso de notificaciones del OS está concedido.
• Las restricciones de batería de Android no bloquean la app durante las pruebas.
• El modo de bajo consumo de iOS y las restricciones de actualización en segundo plano no afectan la entrega en segundo plano.
• La notificación no fue reemplazada por otra con el mismo collapse ID.

Las plataformas de push nativas pueden aceptar una notificación y aun así retrasar, limitar, agrupar o descartar su entrega más adelante. Considera las estadísticas de aceptación del proveedor como “aceptada para entrega”, no como prueba de que el dispositivo la mostró.

Recibida pero no mostrada

Comprobación:

• La app no estaba en primer plano. Las notificaciones en foreground suelen enviarse a JavaScript para que la app decida qué UI mostrar.
• La importancia del canal de notificaciones de Android es suficiente para mostrar una alerta.
• Se concedió el permiso de notificaciones en Android 13+.
• Focus de iOS, el resumen de notificaciones o los ajustes de notificaciones por app no están ocultando la notificación.
• La lógica para limpiar el badge o al abrir la app no está eliminando las notificaciones entregadas durante las pruebas.

Problemas con notificaciones en background

El callback en background no se ejecuta

Las notificaciones en background son best-effort. El OS puede omitirlas.

Comprobación:

• iOS tiene Modos en segundo plano > Notificaciones remotas activado.
• iOS AppDelegate.swift reenvía las notificaciones remotas a CapgoNotificationsRemoteNotification.
• Prueba el comportamiento en segundo plano de iOS en un dispositivo físico.
• El usuario no forzó el cierre de la app.
• El handler en segundo plano llama a finish().
• El trabajo dentro del callback es breve, seguro para la red e idempotente.

En iOS, los pushes en segundo plano pueden limitarse si envías demasiados, tardas mucho o el usuario rara vez abre la app. Es el comportamiento esperado de la plataforma.

Segundo plano iniciado pero no finalizado

Si las estadísticas muestran background_started sin background_finished, es probable que el handler de JavaScript haya fallado, haya expirado o no haya llamado a finish().

Envuelve el handler en try/finally:

await CapgoNotifications.addListener('backgroundNotification', async (event) => {
  try {
    await doShortBackgroundWork(event.notification.data)
  } finally {
    await event.finish()
  }
})

Problemas con el Silent Update Check

Llega la notificación de Update Check pero no se instala la actualización

Comprobación:

• @capgo/capacitor-updater está instalado y configurado.
• autoUpdater es true o enableUpdaterIntegration fue llamado.
• Los ajustes de Notificaciones de la app permiten verificar actualizaciones push.
• El dispositivo de destino pertenece al canal esperado.
• La app tiene un bundle más reciente disponible en Capgo.
• Tu modo de instalación de actualizaciones es correcto: next se encola para el próximo reinicio o ciclo en segundo plano, set se instala en cuanto el updater puede hacerlo de forma segura.

Ejecuta una comprobación manual con la app abierta:

const result = await CapgoNotifications.runUpdateCheck({
  enabled: true,
  installMode: 'next',
})

console.log(result)

Si la comprobación manual devuelve unavailable, revisa primero la configuración del plugin updater.

Problemas con los badges

Comprobación:

• El target se resuelve al dispositivo correcto en la búsqueda de destinatarios.
• La plataforma admite app badges para el launcher o la pantalla de inicio que se esté probando.
• El usuario no ha desactivado los badges en los ajustes de notificaciones del SO.
• La app no limpia los badges inmediatamente al iniciar.
• No estás ejecutando localmente setBadge locales y envíos de badges desde el backend.

Problemas con las stats

Las stats parecen duplicadas

El envío de notificaciones es at-least-once. Los reintentos de la cola o de la plataforma pueden duplicar un envío. Usa notification IDs y collapse IDs cuando la acción de tu app deba ser idempotente.

Faltan estadísticas en dispositivos antiguos

El registro del Analytics Engine es para dispositivos activos, no una base de datos permanente. El plugin debe refrescar el registro al iniciar la app, al renovar el token, al cambiar el ID externo y periódicamente antes de la ventana de retención de dispositivos activos.

Faltan los eventos de apertura (Open Events)

Comprobación:

• La notificación incluye un valor estable id.
• notificationOpened el listener se registra durante el inicio de la app.
• La app no está reemplazando el flujo nativo de apertura con un code personalizado antes de que el plugin lo detecte.
• El usuario pulsó la notificación en lugar de abrir la app manualmente.

Comandos de depuración de API

Buscar un destinatario:

curl -X POST 'https://api.capgo.app/notifications/recipients/lookup' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "externalId": "customer-user-123"
  }'

Leer estadísticas:

curl 'https://api.capgo.app/notifications/stats?app_id=com.example.app&days=7' \
  -H 'x-api-key: CAPGO_API_KEY'

Enviar una prueba en primer plano:

curl -X POST 'https://api.capgo.app/notifications/send' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "target": { "externalId": "customer-user-123" },
    "payload": {
      "title": "Capgo test",
      "body": "Open this notification to test events.",
      "data": { "debug": "true" }
    }
  }'

Causas raíz comunes

Síntoma	Causa probable
Dispositivo ausente en la consulta	register no se llamó, proof no coincide, consentimiento false, app ID no coincide.
Permiso denegado	Prompt del OS denegado o aún no solicitado.
En cola pero sin estadísticas de envío	Faltan credenciales de la plataforma o están desactivadas.
Enviado pero sin estadísticas de recepción	Dispositivo offline, throttling del OS, app forzada a cerrar o token inválido.
Logs de notificación en foreground pero sin banner	La app está en primer plano y debe mostrar su propia UI interna.
En iOS, el modo background nunca se ejecuta.	Faltan capacidades, falta el forwarding del AppDelegate, cierre forzado de la app o limitación del SO.
La comprobación de actualizaciones no hace nada	Integración del updater desactivada, no hay un bundle más reciente, canal incorrecto o error en el modo de instalación.
El badge se reinicia.	El inicio de la app code limpia los badges o hay una race condition entre el badge local y el backend.

Continúa desde Depuración

Una vez que el dispositivo se registra y la notificación de prueba funciona, usa Primeros pasos para integrar badges, segmentación de campañas y comprobaciones de silent update en tu app de producción.