Depuración

Utilice esta lista de verificación cuando una notificación no se registra, no llega, no se muestra o no actualiza Capgo estadísticas.

Comience con El Registro del Dispositivo

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

1. Abra la aplicación y inicie sesión como el usuario que desea probar.
2. Llame CapgoNotifications.register(...) después de la autenticación.
3. En Capgo, abre En __CAPGO_KEEP_0__, abra.
4. Notificaciones > Búsqueda de destinatarios

Busque por el mismo ID de cliente externo.

• recipientKey
• deviceKey
• platform android o ios
• estado de permiso
• app version
• versión del plugin
• etiquetas y atributos

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

Agregar Escuchadores Temporales de Depuración

Agregar escuchadores temporales mientras se prueba. Elimine los registros ruidosos antes de enviar.

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()
})

Recopilar esta Información

Cuando estés depurando con tu equipo o Capgo soporte, recopila:

• Capgo ID de la aplicación.
• ID de paquete de la aplicación o ID de bundle de iOS.
• Plataforma y versión del sistema operativo del dispositivo.
• Versión y número de compilación de la aplicación.
• Versión del plugin.
• ID de cliente externo.
• recipientKey y deviceKey desde la inscripción o búsqueda de destinatarios.
• ID de campaña o ID de notificación.
• Si la aplicación estaba en primer plano, segundo plano, cerrada por fuerza o recién instalada.
• Registros del dispositivo del ejecución que reprodujo el problema.

Usa registros del dispositivo

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

En Android:

• Abre el registro de Android Studio Logcat.
• Filtrar por el ID del paquete de la aplicación.
• Observa la solicitud de permiso de notificación, refresco de token nativo, recepción de mensajes y registros de oyentes de JavaScript.
• Si una notificación visible no se muestra, inspecciona el importancia del canal de notificación y el estado de permiso de Android 13+ primero.

En iOS:

• Ejecuta la aplicación desde Xcode en un dispositivo físico.
• Abre la consola de Xcode o Dispositivos y simuladores registros.
• Filtrar por el ID del paquete y CapgoNotifications.
• Confirmar AppDelegate.swift para enviar notificaciones remotas y que la capacidad de modo de fondo esté habilitada.

Enviar un primer test de primer plano, luego un test de fondo, luego un test de actualización silenciosa. Este orden separa problemas de escucha de JavaScript de límites de entrega de fondo del sistema operativo.

Problemas de registro

CLI Configuración No Terminó

Ejecutar el comando de configuración desde el folder que contiene capacitor.config.*:

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

Si el comando no puede inferir su ID de aplicación, póngalo explícitamente como se muestra arriba. Si la instalación del paquete falla, confirme que el nombre del paquete es @capgo/capacitor-notificationsverifica que tu registro npm esté https://registry.npmjs.org, comprueba el acceso a la red y ejecuta el comando nuevamente.

No se muestra el dispositivo en la búsqueda de destinatarios

Verifica:

• register se llama después de que tu aplicación tenga un usuario autenticado.
• externalId coincide con el ID de usuario que buscas en la consola.
• identityProof se creó por tu backend para el mismo appId y externalId.
• appId en configure coincide con la aplicación Capgo.
• consent No está configurado para false a menos que el usuario se haya opuesto.
• El dispositivo tiene acceso a la red a https://api.capgo.app.
• El token de notificación nativa se creó. Utilice registrationChanged para confirmar la actualización del token.

Identidad no válida

La prueba está vinculada al ID de aplicación Capgo y al ID externo. Si alguno de estos valores cambia, genere una nueva prueba.

No cachee una prueba para siempre ni reutilice una prueba en varias aplicaciones. Genere una nueva desde su servidor después de la autenticación, devuélvala a la aplicación y llame a register.

Dispositivo Registrado Pero Ha Denegado Permiso

El plugin puede registrar el estado del dispositivo incluso cuando el usuario deniega permiso. Puede ver el dispositivo, pero las notificaciones visibles no se mostrarán.

Utilice una pantalla de permisos previa a la solicitud del sistema operativo. Explique qué obtiene el usuario, luego solicite permiso solo cuando el acción tenga sentido.

Problemas de entrega

Programado pero no enviado

Verifique:

• Estado de credenciales de la plataforma es configured en Capgo.
• El entorno del trabajador contiene la referencia secreta exacta mostrada por la consola.
• The package ID or bundle ID in the app matches the platform push setup.
• El público objetivo se resuelve en al menos un dispositivo activo.
• La campaña no está limitada a una etiqueta o segmento que el dispositivo no tiene.

Enviado pero no recibido

Verificar:

• El dispositivo está en línea.
• No se ha detenido la aplicación por el usuario.
• La notificación del sistema operativo tiene permiso.
• No hay restricciones de batería de Android que bloqueen la aplicación durante la prueba.
• iOS Modo de bajo consumo y restricciones de refresco de fondo no están afectando la entrega de fondo.
• No se ha reemplazado la notificación por otra notificación con el mismo ID de colapso.

Las plataformas de notificación nativas pueden aceptar una notificación y aún retrasar, limitar, colectar o descartar la entrega más tarde. Trate los estadísticas de aceptación de proveedores como “aceptado para la entrega”, no como prueba de que el dispositivo la mostró.

Recibido pero no mostrado

Verificar:

• La aplicación no estaba en primer plano. Las notificaciones de primer plano suelen entregarse a JavaScript para que tu aplicación decida qué interfaz mostrar.
• La importancia del canal de notificación de Android es lo suficientemente alta como para mostrar una alerta.
• Se ha concedido permiso de notificación de Android 13+.
• iOS Focus, resumen de notificaciones o ajustes de notificaciones por aplicación no están ocultando la notificación.
• Badge clearing or app-open logic is not removing delivered notifications during testing.

Notificaciones de fondo: Problemas

No se ejecuta la llamada de fondo

Notificaciones de fondo son de mejor esfuerzo. El sistema operativo puede saltarlas.

Verificar:

• iOS tiene Modos de fondo > Notificaciones remotas enabled.
• iOS AppDelegate.swift envía notificaciones remotas a CapgoNotificationsRemoteNotification.
• Prueba el comportamiento de fondo de iOS en un dispositivo físico.
• La aplicación no fue cerrada por el usuario.
• El manejador de fondo llama a finish().
• El trabajo dentro del callback es corto, seguro de red y idempotente.

En iOS, los empujones de fondo pueden ser ralentizados si envías demasiados, utilizas demasiado tiempo o el usuario rara vez abre la aplicación. Este es el comportamiento de plataforma esperado.

Comienzo de fondo pero no finalizado

If los estadísticos muestran background_started sin background_finished, el manejador de JavaScript probablemente lanzó, se agotó o no llamó finish().

Envuelve el manejador en try/finally:

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

Problemas de Verificación de Actualizaciones Silenciosas

Update Check Notification Arrives But No Update Installs

Verificar:

• @capgo/capacitor-updater si está instalado y configurado.
• autoUpdater si true o enableUpdaterIntegration se llamaba
• The app’s Notifications settings allow push update checks.
• El dispositivo objetivo pertenece al canal que esperas.
• La aplicación tiene una versión más reciente disponible en Capgo.
• espera a la próxima reiniciación o ciclo de fondo next filas para el próximo reinicio o ciclo de fondo set Ejecuta una comprobación manual mientras la aplicación está abierta:

Run a manual check while the app is open:

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

console.log(result)

inspecciona la configuración del plugin de actualizador primero. unavailable, inspect the updater plugin setup first.

Problemas de Badges

Verificar:

• El objetivo resuelve el dispositivo correcto en la búsqueda de destinatarios.
• La plataforma admite badges de aplicaciones para el lanzador o pantalla de inicio que se está probando.
• The user has not disabled badges in OS notification settings.
• La aplicación no elimina las badges de inmediato al iniciar.
• No estás ejecutando localmente setBadge Problemas de Estadísticas

Sección titulada “Problemas de Estadísticas”

Estadísticas Repetidas

La notificación se envía al menos una vez. La cola de reintentos y la plataforma de reintentos pueden duplicar un envío. Utilice IDs de notificación y IDs de colapso cuando la acción de la aplicación debe ser idempotente.

Estadísticas faltan para dispositivos antiguos

El registro del motor de análisis es para dispositivos activos, no una base de datos para siempre. El complemento debe refrescar la inscripción al iniciar la aplicación, al refrescar el token, al cambiar el ID externo y periódicamente antes de la ventana de retención de dispositivos activos.

Eventos abiertos faltan

Verifique:

• La notificación incluye un identificador estable id.
• notificationOpened El escuchador se registra durante el arranque de la aplicación.
• No se está reemplazando el flujo de apertura nativo con un code personalizado antes de que el complemento lo vea.
• El usuario realmente pulsó la notificación en lugar de abrir la aplicación manualmente.

API Comandos de depuración

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 un test de 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 de raíz común

Síntoma	Causa probable
Dispositivo faltante en la búsqueda	register no se llama, desacuerdo de prueba, consentimiento falso, desacuerdo de ID de aplicación.
Denegado el permiso	El sistema operativo no ha solicitado permiso.
Programado pero sin estadísticas enviadas	Los credenciales de la plataforma están ausentes o deshabilitadas.
Enviados pero sin estadísticas recibidas	Device offline, OS throttling, app force-stopped, or token invalid.
Registros de notificaciones de primer plano pero sin bandeja	App is foregrounded and must show its own in-app UI.
No se ejecuta en segundo plano en iOS	Missing capabilities, missing AppDelegate forwarding, force-quit app, or OS throttling.
No se realiza el control de actualizaciones	La integración del actualizador está deshabilitada, no hay un paquete más nuevo, el canal o el modo de instalación están mal entendidos.
Resetea la insignia	App startup code clears badges or local and backend badge writes race.

Sigue adelante desde Depuración

Después del dispositivo se registre y una notificación de prueba funcione, utilice Getting Started to wire badges, campaign targeting, and silent update checks into your production app.