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(...) contexto: Fragmento de texto HTML de una cadena de Capgo UI más larga (clave de la página `appflow_migration_step2`). Página/área: Comparación y migración de Appflow / marketing de copia. Rol: Oración de copia de sitio web. Visto en: página ionic-appflow.astro. Preservar términos de producto/marca y desarrollador de Capgo exactamente. Clave de mensaje `appflow_migration_step2` (Paso 2 de la migración de Appflow).
3. En Capgo, abra Notificaciones > Búsqueda de destinatarios.
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
• versión de la aplicación
• versión del plugin
• etiquetas y atributos

Si la búsqueda no 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()
})

Recopilar esta información

Cuando depures 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 o registro o búsqueda de destinatario.
• ID de campaña o ID de notificación.
• Si la aplicación estaba 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:

• Abra el registro de Android Studio Logcat.
• Filtre por el ID de paquete de la aplicación.
• Esté atento a los registros de solicitud de permiso de notificación, refresco de token nativo, recepción de mensajes y registros de escucha de JavaScript.
• Si una notificación visible no se muestra, inspeccione la importancia del canal de notificaciones 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.
• Filtre por el ID de paquete y CapgoNotifications.
• Confirmar AppDelegate.swift que las notificaciones remotas se envían y que la capacidad de modo de fondo está habilitada.

Envíe una prueba de primer plano, luego una prueba de fondo, y luego una prueba de actualización silenciosa. Este orden separa problemas de escuchas de JavaScript de límites de entrega de fondo del sistema.

Problemas de registro

CLI Configuración No Se Completó

Ejecuta la orden de configuración desde el directorio que contiene capacitor.config.*:

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

Si la orden no puede inferir tu ID de aplicación, pasa uno explícitamente como se muestra arriba. Si la instalación de paquetes falla, confirma que Capgo ha habilitado el acceso a paquetes de vista previa privada para tu npm cuenta, luego vuelve a ejecutar la orden.

El Dispositivo No Aparece 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 fue creado por tu servidor de backend para el mismo appId y externalId.
• appId in configure se ajusta a 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 con 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 a la ID de aplicación Capgo y la ID externa. Si alguno de los valores cambia, 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 iniciar sesión, devuélvala a la aplicación y llame register.

Dispositivo Registrado Pero Tiene Denegada La Permiso

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

Utiliza una pantalla de primeros pasos de permiso antes de la solicitud del sistema operativo. Explica qué obtiene el usuario, luego pregunta por el permiso solo cuando la acción tenga sentido.

Problemas De Envío

Programado Pero No Enviado

Verifica:

• El estado del credencial de plataforma es configured en Capgo.
• El entorno del trabajador contiene la referencia secreta exacta mostrada por la consola.
• El identificador del paquete o el identificador de la cesta en la aplicación coincide con la configuración de envío de la plataforma.
• La audiencia 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.
• La aplicación no fue detenida por fuerza por el usuario.
• La permiso de notificación del sistema operativo está concedido.
• 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, ralentizar, colectar o descartar la entrega más tarde. Trate los estadísticas de proveedor aceptadas como “aceptadas para entrega”, no como prueba de que el dispositivo la mostró.

Recibido pero no mostrado

Verifique:

• No se había puesto el app en primer plano. Las notificaciones de primer plano se entregan normalmente a JavaScript para que la app decida qué UI 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+.
• Los ajustes de resumen de notificación, resumen de enfoque o configuración de notificaciones por aplicación de iOS no están ocultando la notificación.
• No se está eliminando la notificación entregada durante la prueba mediante la lógica de eliminación de la insignia o la apertura de la app.

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.
• Puedes probar 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 estar limitados si envías demasiados, utilizas demasiado tiempo o el usuario rara vez abre la aplicación. Este es el comportamiento de plataforma esperado.

Empezado en segundo plano pero no terminado

Si los estadísticas muestran background_started sin background_finished, el manejador de JavaScript probablemente lanzó una excepción, se ha agotado el tiempo o no ha llamado 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 comprobación de actualizaciones silenciosas

La notificación de comprobación de actualizaciones llega pero no se instalan actualizaciones

Verificar:

• @capgo/capacitor-updater está instalado y configurado.
• autoUpdater o true o enableUpdaterIntegration o
• o
• o
• The app has a newer bundle available in Capgo.
• o next o set o

o

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

console.log(result)

Si la comprobación manual devuelve unavailableInspeccione la configuración del plugin de actualización antes.

Problemas de Badges

Compruebe:

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

Problemas de Estadísticas

Estadísticas Parecen 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 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 motor de análisis de registro es para dispositivos activos, no una base de datos para siempre. El plugin 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.

Los Eventos Abiertos Faltan

Verifique:

• 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 nativa 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 comunes

Síntoma	Causa probable
Dispositivo faltante en la búsqueda	register no llamado, prueba no coincidente, consentimiento falso, ID de aplicación no coincidente.
Permiso denegado	Denegado o no solicitado aún la ventana de OS
Programado pero sin estadísticas de envío	Faltan o están deshabilitados los credenciales de la plataforma
Enviado pero no se reciben estadísticas	Dispositivo fuera de línea, frenado por el sistema operativo, aplicación forzada a cerrar o token inválido.
Se registran los registros de notificaciones de primer plano pero no de banner	La aplicación está 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 no está configurado para reenviar, se forzó a cerrar la aplicación o frenado por el sistema operativo.
La verificación de actualizaciones no hace nada	La integración del actualizador está deshabilitada, no hay una versión más nueva, canal incorrecto o modo de instalación malentendido.
La insignia se resetea	Al iniciar la aplicación code se borran las insignias o se produce una carrera entre las escrituras locales y de backend de insignias.

Sigue adelante desde Depuración

Después del dispositivo se registra y una notificación de prueba funciona, utilice Iniciar para conectar las banderas, la publicidad de campaña y las comprobaciones de actualizaciones silenciosas en tu aplicación de producción.