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 firma de inicio de sesión.
3. En Capgo, abra Notificaciones > Búsqueda de destinatarios.
4. Busque 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
• versión de la aplicación
• versión del complemento
• etiquetas y atributos

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 escuchadores temporales durante la prueba. Elimine 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()
})

Recolecta esta Información

Cuando debugas con tu equipo o Capgo soporte, recolecta:

• 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 destinatario.
• ID de campaña o ID de notificación.
• ¿Estaba la aplicación en primer plano, fondo, cerrada por fuerza o recién instalada?
• Registros del dispositivo desde la ejecución que reprodujo el problema.

Usar Registros del Dispositivo

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

En Android:

• Abrir Android Studio Logcat.
• Filtrar por el ID del paquete de la aplicación.
• Busque los registros de 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, inspeccione el importancia del canal de notificación y el estado de permiso de Android 13+ primero.

En iOS:

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

Envíe un primer test de antecedencia, luego un test de fondo, luego un test de actualización silenciosa. Este orden separa problemas de escuchas 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 carpeta 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 que Capgo ha habilitado el acceso a paquetes de vista previa privada para su npm cuenta, luego vuelva a ejecutar el comando.

El dispositivo no aparece en la búsqueda de destinatarios

Verificar:

• 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 fue creado por su servidor backend para el mismo appId y externalId.
• appId en configure coincide con la aplicación Capgo.
• consent no se ha configurado false a menos que el usuario haya optado por no hacerlo.
• El dispositivo tiene acceso a la red https://api.capgo.app.
• Se creó el token de notificación nativa. 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 se modifican cualquiera de estos valores, genere una nueva prueba.

No cache una prueba durante todo el tiempo o reutilice una prueba en varias aplicaciones. Génela 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.

Use a permission primer screen before the OS prompt. Explain what the user gets, then ask for permission only when the action makes sense.

Problemas de Entrega

No Enviado Aunque Programado

Verificar:

• El estado de credenciales de plataforma es configured in Capgo.
• El entorno del trabajador contiene la referencia secreta exacta mostrada por la consola.
• El ID del paquete o el ID de la caja en la aplicación coincide con la configuración de envío de la plataforma.
• 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.

No Enviado, No Recibido

Verificar:

• El dispositivo está en línea.
• La aplicación no fue detenida por el usuario.
• Se ha concedido la permiso de notificación del sistema operativo.
• Las restricciones de batería de Android no están bloqueando la aplicación durante la prueba.
• Las restricciones de modo de bajo consumo de iOS y actualización 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 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 proveedor como “aceptado para entrega”, no como prueba de que el dispositivo la mostró.

Recibido, No Mostrado

Verificar:

• La aplicación no se encontraba en primer plano. Las notificaciones de primer plano se entregan normalmente a JavaScript para que la aplicación decida qué interfaz de usuario mostrar.
• La importancia del canal de notificación de Android es lo suficientemente alta como para mostrar una alerta.
• Se ha concedido la permiso de notificación de Android 13+.
• Los ajustes de notificación de iOS, resumen de notificación o ajustes de notificación por aplicación no están ocultando la notificación.
• La lógica de eliminación de notificaciones durante la prueba no está eliminando las notificaciones entregadas.

Problemas de Notificaciones de Fondo

No se ejecuta el Callback de Fondo

Las notificaciones de fondo son de mejor esfuerzo. El sistema operativo puede saltarlas.

Verificar:

• 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, que es corto, seguro para la red y idempotente.

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

Iniciado en segundo plano pero no finalizado

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

Envuelva el manejador en try/finally:

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

Problemas de Silent Update Check

La notificación de actualización llega pero no se instala ninguna actualización

Verificar:

• @capgo/capacitor-updater está instalado y configurado.
• autoUpdater está instalado y configurado. true o fue llamado. enableUpdaterIntegration Las configuraciones de notificaciones de la aplicación permiten comprobaciones de actualizaciones push.
• El dispositivo objetivo pertenece al canal que esperas.
• La aplicación tiene un paquete más nuevo disponible en __CAPGO_KEEP_0__.
• The app has a newer bundle available in Capgo.
• se coloca en cola para la próxima reiniciación o ciclo de fondo. next se instala tan pronto como el actualizador puede hacerlo de manera segura. set Realiza una comprobación manual mientras la aplicación está abierta:

Copiar a portapapeles

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

console.log(result)

, revisa la configuración del plugin de actualizador primero. unavailable]} ]}

Problemas de Insignia

Verificar:

• El objetivo resuelve el dispositivo correcto en la búsqueda de destinatarios.
• La plataforma admite insignias de aplicación para el lanzador o pantalla de inicio que se está probando.
• El usuario no ha deshabilitado las insignias en los ajustes de notificaciones del sistema.
• La aplicación no elimina las insignias de inmediato al iniciar.
• No estás realizando pruebas locales de llamadas contra envíos de insignias de backend. setBadge Problemas de Estadísticas

Sección titulada “Problemas de Estadísticas”

Estadísticas duplicadas

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

Faltan Estadísticas 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.

Están Faltando Eventos Abiertos

Verificar:

• La notificación incluye un identificador estable id.
• notificationOpened El escuchador se registra durante el arranque de la aplicación.
• La aplicación no 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 comunes

Síntoma	Causa probable
Dispositivo faltante en la búsqueda	register no llamado, prueba de coincidencia, consentimiento falso, ID de aplicación desacordada.
Denegado permiso	Pregunta de sistema OS denegada o no solicitada aún.
Programado pero sin estadísticas de envío	Credenciales de plataforma faltantes o deshabilitadas.
Enviado pero sin estadísticas de recepción	Dispositivo fuera de línea, OS ralentizando, aplicación forzada detenida o token inválido.
Registros de notificaciones de primer plano pero sin banner	La aplicación se encuentra en primer plano y debe mostrar su propia interfaz de usuario en la aplicación.
El fondo nunca se ejecuta en iOS	Faltan capacidades, AppDelegate de reenvío faltante, aplicación de fuerza de cierre o freno del sistema.
La verificación de actualizaciones no hace nada	La integración del actualizador está deshabilitada, no hay un paquete más nuevo, el canal equivocado o la comprensión de la modalidad de instalación.
La insignia se resetea	El arranque de la aplicación code elimina las insignias o las escrituras de insignias locales y de servidor que se ejecutan en paralelo.

Sigue adelante desde Depuración

Después de que el dispositivo se registra y una notificación de prueba funciona, utilice Iniciación para conectar insignias, objetivos de campaña y verificaciones de actualizaciones silenciosas en tu aplicación de producción.