Depuración

Utilice este checklist cuando una notificación no se registra, no llega, no 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, abra Notificaciones > Búsqueda de destinatario.
4. Buscar por el mismo ID de cliente externo.

Deberías ver al menos un dispositivo activo con:

• recipientKey
• deviceKey
• plataforma android o ios
• estado de permiso
• estado de permiso
• versión de la aplicación
• versión del complemento

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

Agregar Escuchadores de Depuración Temporales

Agregar oyentes temporales durante la 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 paquete 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 destinatario.
• 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.
• Registro de dispositivo desde la ejecución que reprodujo el problema.

Usar Registros de Dispositivo

Mantenga conectado un dispositivo real mientras envía una notificación de prueba.

En Android:

• Abrir Logcat de Android Studio.
• Filtrar por el ID del paquete de la aplicación.
• Mire los registros de solicitud de permiso de notificación, refresco de token nativo, recepción de mensaje y registros de oyente de JavaScript.
• Si una notificación visible no se muestra, inspeccione el estado de importancia del canal de notificación y el estado de permiso de Android 13+ primero.

En iOS:

• Correr la aplicación desde Xcode en un dispositivo físico.
• Abra la consola de Xcode o Dispositivos y Simuladores registros.
• Filtrar por el ID de paquete y CapgoNotifications.
• Confirmar AppDelegate.swift permite notificaciones remotas y que la capacidad de modo de fondo esté habilitada.

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

Problemas de registro

CLI Configuración No Terminó

Ejecute 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, pase explícitamente como se muestra arriba. Si la instalación de paquetes falla, confirme el nombre del paquete es @capgo/capacitor-notificationsverifique su npm registro es https://registry.npmjs.org, comprueba el acceso a la red y ejecuta el comando nuevamente.

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

Verifique:

• register se llama después de que su aplicación tenga un usuario autenticado.
• externalId coincide con el ID de usuario que busca en la consola.
• identityProof ha sido creada por su servidor de backend para el mismo appId y externalId.
• appId en configure corresponde 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 https://api.capgo.app.
• El token de notificación nativa se creó. Utilice registrationChanged para confirmar la actualización del token

Identidad Invá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 cachen una prueba para siempre o reutilicen una prueba en varias aplicaciones. Llámelo desde su servidor de backend después de iniciar sesión, devuélvalo a la aplicación y llámelo register.

Dispositivo Registrado Pero Ha Denegado Permiso

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

Antes de la solicitud del sistema operativo, muestra una pantalla de permisos inicial para explicar a qué se refiere el permiso solicitado.

Problemas de Entrega

Programado Pero No Enviado

Verifique:

• Estatus de credenciales de 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 a 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.
• La aplicación no fue detenida por el usuario.
• La notificación del sistema operativo tiene permiso.
• Las restricciones de batería de Android no están bloqueando 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.
• La notificación no fue reemplazada por otra notificación con el mismo ID de colapso.

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

Recibida pero no mostrada

Verifique:

• 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 para mostrar una alerta.
• La permiso de notificación de Android 13+ está concedido.
• 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.

Problemas de notificaciones de fondo

Llamada de fondo no se ejecuta

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

Verifique:

• iOS tiene Modos de fondo > Notificaciones remotas habilitado.
• 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 finish().
• Trabaja dentro del callback, es corto, seguro de red y idempotente.

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

Comenzado en segundo plano pero no terminado

Si los estadísticas muestran background_started sin background_finishedLa función JavaScript probablemente lanzó un error, se quedó sin tiempo 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 con la Verificación de Actualizaciones Silenciosa

Update Check Notification Arrives But No Update Installs

Verificar:

• @capgo/capacitor-updater está instalado y configurado.
• autoUpdater o true o enableUpdaterIntegration o se llamó.
• Las configuraciones de notificaciones del app permiten verificaciones de actualización.
• El dispositivo objetivo pertenece al canal que esperas.
• El app tiene una versión más reciente disponible en Capgo.
• Tu modo de instalación de actualizaciones es correcto: next filas para el próximo reinicio o ciclo de fondo. set se instala tan pronto como el actualizador puede hacerlo de manera segura

Run a manual check while the app is open:

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

console.log(result)

Si la comprobación manual devuelve unavailable, inspect the updater plugin setup first.

Problemas de Badges

Verificar:

• La resolución del destino apunta al dispositivo correcto en la búsqueda de destinatarios.
• La plataforma admite badges de aplicación para el lanzador o pantalla de inicio que se está probando.
• El usuario no ha deshabilitado las notificaciones en los ajustes de la OS.
• La aplicación no elimina las badges de inmediato al iniciar.
• No estás ejecutando localmente setBadge llamadas contra backend insignia envía.

Problemas de estadísticas

Estadísticas Parecen Duplicadas

La notificación de envío es 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 idópeta.

Estadísticas Faltan Para Dispositivos Antiguos

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

Eventos Abiertos Faltan

Verifique:

• La notificación incluye una versión estable id.
• notificationOpened El escuchador se registra durante el arranque de la aplicación.
• La aplicación no está sustituyendo el flujo abierto nativo con un code personalizado antes de que el plugin 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"
  }'

Ver 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 comunes

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.
Permiso denegado	Solicitud de OS denegada o no solicitada aún.
Programado pero sin estadísticas enviadas	Las credenciales de la plataforma están ausentes o deshabilitadas.
Estadísticas enviadas pero no recibidas.	Device offline, OS throttling, app force-stopped, or token invalid.
Registros de notificaciones de primer plano pero sin banner	App is foregrounded and must show its own in-app UI.
El fondo nunca se ejecuta en iOS.	Missing capabilities, missing AppDelegate forwarding, force-quit app, or OS throttling.
La verificación de actualizaciones no hace nada.	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.
La insignia se resetea.	App startup code clears badges or local and backend badge writes race.

Siga adelante desde la depuración

Después del dispositivo se registra y una notificación de prueba funciona, utilice Obtener Empezar para conectar medallas, objetivos de campaña y verificaciones de actualizaciones silenciosas en tu aplicación de producción.