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 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. In Capgo, abre 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
• o
• 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 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íe 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.
• If a visible notification does not show, inspect the notification channel importance and Android 13+ permission state first.

On iOS:

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

Envía 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 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.

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 dado de baja.
• 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 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. Genere una nueva desde su servidor después de iniciar sesión, devuélvala a la aplicación y llame a register.

Dispositivo Registrado Pero Tiene Denegada La Permiso

El plugin puede registrar el estado del dispositivo incluso cuando el usuario deniega la 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 la permiso solo cuando la acción tenga sentido.

Problemas De Envío

Cola Pero No Enviado

Verifica:

• El estado de la 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 caja 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 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.
• Los límites de bajo consumo de iOS y la 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 ejecutaba la aplicación 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 para mostrar una alerta.
• Se ha concedido la autorización de notificación de Android 13+.
• Los ajustes de notificación de iOS, resumen de notificación o configuración de notificación por aplicación no están ocultando la notificación.
• No se eliminan las notificaciones entregadas durante la prueba mediante la lógica de eliminación de la insignia o la apertura de la aplicación.

Problemas de notificaciones de fondo

No se ejecuta el callback de fondo

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.

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

Comenzado en segundo plano pero no finalizado

Si los estadísticas muestran background_started sin background_finished, el manejador de JavaScript probablemente lanzó, se agotó el 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 silenciosa de actualizaciones

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

Verificar:

• @capgo/capacitor-updater está instalado y configurado.
• autoUpdater es true o enableUpdaterIntegration ¿o
• se llamaba.
• Las configuraciones de notificaciones del app permiten comprobar actualizaciones push.
• The app has a newer bundle available in Capgo.
• La app tiene una versión más reciente disponible en __CAPGO_KEEP_0__. next Tu modo de instalación de actualizaciones es correcto: set espera a la próxima reiniciación o ciclo de fondo

se instala tan pronto como el actualizador puede hacerlo de manera segura.

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

Verifique:

• 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 de badges en los ajustes de notificaciones del sistema.
• La aplicación no elimina las badges de inmediato al iniciar.
• No está realizando llamadas locales setBadge contra envíos de badges 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 idópeta.

Las 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 registro en el inicio de la aplicación, refresco de token, 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 flujo personalizado code 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"
  }'

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 el prompt del sistema operativo.
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.
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, la aplicación se cerró forzadamente o el sistema operativo está frenando.
La verificación de actualizaciones no hace nada	La integración del actualizador está deshabilitada, no hay una versión más nueva, el canal es incorrecto o el modo de instalación está mal entendido.
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 Inicio para conectar medallas, objetivos de campaña y comprobaciones de actualizaciones silenciosas en tu aplicación de producción.