Depuración

Copie un prompt de configuración con los pasos de instalación y la guía de markdown completa para este plugin.

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.

Abra la aplicación y inicie sesión como el usuario que desea probar.
Llame CapgoNotifications.register(...) contexto: texto fragmento de HTML de una cadena de Capgo UI más larga (clave de la página `appflow_migration_step2`). Área: Comparación y migración de Appflow / marketing de copia de página. 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). Llame después de la firma de inicio de sesión.
En Capgo, abra Notificaciones > Búsqueda de destinatarios.
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 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 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.
Registro del 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:

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 escuchas 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 Filtra por el ID de paquete y
Confirmar CapgoNotifications.
para que las notificaciones remotas se envíen y que la capacidad de modo de fondo esté habilitada. AppDelegate.swift 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 escuchas de JavaScript de límites de entrega de fondo del sistema operativo.

Problemas de registro

Título de la sección “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 el nombre del paquete es @capgo/capacitor-notificationsverifica que tu registro npm esté https://registry.npmjs.orgverifica el acceso a la red, luego vuelve a ejecutar la orden.

El Dispositivo No Aparece En La Búsqueda De Destinatarios

Revisa:

register se llama después de que tu aplicación tenga un usuario autenticado.
externalId coincide con el ID de usuario que estás buscando en la consola.
identityProof fue emitido 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 haya optado por salir.
El dispositivo tiene acceso a la red de https://api.capgo.app.
El token de notificación nativa se creó. Utiliza registrationChanged para confirmar la actualización del token.

Identidad Inválida

La prueba está vinculada a la ID de la aplicación Capgo y la ID externa. Si cualquiera de estos valores cambia, genere una nueva prueba.

No guarde 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 llámela. register.

Dispositivo Registrado Pero Denegó 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.

Utilice una pantalla de recordatorio de permisos antes de la solicitud del sistema operativo. Explique qué obtendrá el usuario y luego solicite permiso solo cuando la acción tenga sentido.

Problemas de Entrega

Pendiente de Envío

Verifique:

Estado del credencial de plataforma es configured en Capgo.
El entorno del trabajador contiene la referencia secreta exacta mostrada por la consola de dashboard.
El ID del paquete o el ID de la cesta en la aplicación coincide con la configuración de empuje 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.

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.
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 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 aceptación de proveedor como “aceptado para 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 se entregan normalmente a JavaScript para que la 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+.
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.
La lógica de eliminación de notificaciones al abrir la aplicación o la eliminación de la insignia no están eliminando las notificaciones entregadas durante la prueba.

Problemas de notificaciones de fondo

No se ejecuta la llamada 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, 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.

Comenzado en Fondo pero No Terminado

Si los stats 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 de Verificació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 instala tan pronto como el actualizador pueda hacerlo de manera segura.

Ejecuta una comprobación manual mientras la aplicación está abierta:

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

console.log(result)

Si la comprobación manual devuelve unavailableinspecciona la configuración del plugin de actualizador primero.

Problemas de Badges

Verifica:

La resolución del destino apunta al 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 llamadas contra el emblema de backend envía.

Problemas de estadísticas

Las 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 su 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 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

Verificar:

La notificación incluye un escuchador estable id.
notificationOpened El escuchador estable se registra durante el arranque de la aplicación.
La aplicación no está reemplazando el flujo de apertura nativo con un flujo personalizado code 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.
Estados programados pero no enviados	Faltan credenciales de plataforma o están deshabilitadas.
Enviados pero no recibidos	El dispositivo está desconectado, el sistema operativo está limitando el rendimiento, la aplicación se ha detenido forzosamente o el token es inválido.
Se registran notificaciones de fondo pero no de banner	La aplicación debe mostrar su propia interfaz de usuario en pantalla principal.
El fondo nunca se ejecuta en iOS	Faltan capacidades, AppDelegate no está configurado para reenviar, la aplicación se ha detenido forzosamente o el sistema operativo está limitando el rendimiento.
La verificación de actualizaciones no hace nada	La integración de actualizaciones está deshabilitada, no hay una versión más reciente, el canal es incorrecto o el modo de instalación está mal entendido.
La insignia se resetea	El arranque de la aplicación code elimina las insignias o las escrituras locales y de backend se cruzan.

Sigue adelante desde Depuración

Después de que el dispositivo se registre y una notificación de prueba funcione, utilice Iniciación Editar página