Primeros pasos

@capgo/capacitor-notifications es el plugin de Capgo oficial para notificaciones push nativas en iOS y Android. Está diseñado para el dashboard de Capgo, la API pública, el registro de dispositivos de Analytics Engine, estadísticas de campañas, actualizaciones de badges y comprobaciones silenciosas de Live Update.

Requisitos

• Una app de Capacitor ya añadida a Capgo.
• Acceso a la pestaña de Notifications de la app Capgo.
• Una Capgo API con acceso de escritura para el minting de pruebas de backend y envíos de API.
• Autoridad de push para la plataforma iOS y/o Android de la app.
• @capgo/capacitor-updater if you want silent push update checks.

Inicio rápido

import { CapacitorNotifications } from '@capgo/capacitor-notifications';
await CapacitorNotifications.register({ customerUserId: 'signed-id' });

Errores comunes

• Usa valores de customerUserId firmados desde tu backend.
• Solicita permiso de notificaciones antes de registrarte.
• Verifica las credenciales de Capgo en el dashboard.

1. Configura las credenciales de la plataforma Capgo

Abre la app en Capgo y luego ve a Notificaciones.

Añade una entrada de credenciales por cada plataforma que quieras soportar:

• Android - ID del paquete de la app y metadatos del proyecto de push de Android.
• iOS - bundle ID, team ID, key ID y los metadatos de la clave de push de iOS correspondiente.

Capgo muestra el nombre exacto del secret del entorno que debe existir en el worker de API antes de marcar la plataforma como configurada. El dashboard almacena los metadatos y la referencia al secret esperado. La credencial privada permanece en el entorno del worker.

2. Instalar

Para una configuración más rápida, ejecuta el Capgo CLI desde tu proyecto:

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

El comando instala el paquete de notificaciones, guarda la configuración del plugin de Capacitor, crea un pequeño archivo helper y ejecuta Capacitor sync. Usa esta ruta para apps nuevas a menos que necesites configurar cada archivo manualmente.

Instalación manual:

bun add @capgo/capacitor-notifications @capgo/capacitor-updater
bunx cap sync

Si no usas comprobaciones silenciosas de Capgo, puedes omitir @capgo/capacitor-updater.

3. Configurar el plugin

Configura el plugin una sola vez al iniciar tu app.

import { CapgoNotifications } from '@capgo/capacitor-notifications'

await CapgoNotifications.configure({
  appId: 'com.example.app',
  autoUpdater: true,
  updateInstallMode: 'next',
})

Usa updateInstallMode: 'next' para descargar una actualización e instalarla en el próximo reinicio o ciclo en segundo plano. Usa updateInstallMode: 'set' solo cuando quieras que Capgo instale la actualización en cuanto el updater pueda hacerlo de forma segura.

4. Generar prueba de identidad

No incluyas tu clave Capgo API en la app móvil. Tu backend debe solicitar a Capgo un identityProof después de que la autenticación de tu usuario sea exitosa.

curl -X POST 'https://api.capgo.app/notifications/recipients/proof' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "externalId": "customer-user-123"
  }'

Devuelve el identityProof a la app junto con la respuesta de tu propia sesión.

5. Registrar el dispositivo

Registra el dispositivo solo cuando sepas qué usuario cliente ha iniciado sesión.

const registration = await CapgoNotifications.register({
  externalId: 'customer-user-123',
  identityProof,
  tags: ['paid', 'beta'],
  attributes: {
    plan: 'team',
    locale: 'en-US',
  },
  consent: true,
})

console.log(registration.recipientKey, registration.deviceKey)

Llama a register de nuevo cuando:

• La app se inicia.
• El token de push nativo cambia.
• El usuario autenticado cambia.
• Cambian los tags, los atributos o el consentimiento.
• La app no ha actualizado el registro en mucho tiempo.

6. Añadir Event Listeners

Registra los listeners al iniciar la app para que JavaScript pueda detectar los eventos de foreground, opened y background.

await CapgoNotifications.addListener('registrationChanged', () => {
  void CapgoNotifications.register({
    externalId: currentUser.id,
    identityProof: currentUser.capgoNotificationProof,
    tags: currentUser.notificationTags,
    consent: currentUser.pushConsent,
  })
})

await CapgoNotifications.addListener('notificationReceived', (notification) => {
  console.log('Notification received', notification)
})

await CapgoNotifications.addListener('notificationOpened', (event) => {
  console.log('Notification opened', event.notification.id)
})

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

Llamar siempre a finish() para notificaciones en background una vez terminado tu proceso. Mantén el proceso corto e idempotente.

7. Configuración de iOS

En Xcode, abre el target de la app y habilita:

• Notificaciones push
• Modos en segundo plano > Notificaciones remotas

Reenviar notificaciones remotas desde ios/App/App/AppDelegate.swift:

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    NotificationCenter.default.post(name: Notification.Name("CapgoNotificationsRemoteNotification"), object: userInfo)
    completionHandler(.newData)
}

Luego ejecuta:

bunx cap sync ios

Usa un dispositivo iOS físico al probar las notificaciones en segundo plano. Los simuladores son útiles para trabajar la UI, pero no representan el comportamiento de los push en segundo plano en producción.

8. Configuración de Android

Ejecuta:

bunx cap sync android

Luego verifica:

• Tus credenciales de la plataforma Android están configuradas en Capgo.
• El package ID de la app coincide con el usado para la configuración de push.
• Se solicita el permiso de notificaciones de Android 13+ antes de mostrar notificaciones.
• La app tiene un icono de notificación y una estrategia de canales acorde a tu marca.
• Pruebas en un dispositivo físico o emulador con Google Play services.

Crea un canal de Android por defecto al iniciar tu app:

await CapgoNotifications.configure({ appId: 'com.example.app' })

await CapgoNotifications.register({
  externalId: currentUser.id,
  identityProof: currentUser.capgoNotificationProof,
  consent: true,
})

El plugin declara el servicio de mensajería push de Android. Mantén las políticas de backup, extracción de datos, seguridad de red e icono de notificación en la app host.

9. Envía una notificación de prueba

Usa Notificaciones > Envío de prueba en Capgo, o llama a la API pública desde tu backend:

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": "Hello from Capgo",
      "body": "This is a test notification.",
      "data": { "screen": "inbox" }
    }
  }'

Para una campaña, créala en el dashboard o llama a /notifications/campaigns, luego envíala a un ID externo, tag, segmento o audiencia de broadcast.

10. Configurar badges

await CapgoNotifications.setBadge(4)
await CapgoNotifications.incrementBadge()
await CapgoNotifications.clearBadge()

Desde tu backend:

curl -X POST 'https://api.capgo.app/notifications/badge' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "target": { "externalId": "customer-user-123" },
    "badge": 4
  }'

11. Activar chequeos silenciosos

Silent update checks connect this plugin with @capgo/capacitor-updater.

En la app:

await CapgoNotifications.enableUpdaterIntegration({
  enabled: true,
  installMode: 'next',
})

En Capgo, activa Enviar actualización push a los usuarios en los ajustes de Notifications de la app. Luego, envía un update check desde el dashboard o API:

curl -X POST 'https://api.capgo.app/notifications/update-check' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "target": { "externalId": "customer-user-123" },
    "installMode": "next"
  }'

La notificación es silenciosa y usa un collapse ID para que las actualizaciones repetidas se reemplacen entre sí si la plataforma lo permite.

Lista de verificación

• La app aparece en la búsqueda de destinatarios de Capgo para el esperado externalId.
• El permiso es granted o el usuario ha aceptado el permiso de notificaciones.
• La plataforma registrada es android o ios.
• registrationChanged se dispara tras un refresh del token.
• Un test en foreground registra notificationReceived.
• Abrir los logs de notificaciones notificationOpened.
• Las estadísticas del dashboard muestran eventos en cola y enviados, y luego recibidos/abiertos cuando el dispositivo los reporta.
• Los checks de silent update registran un resultado de runUpdateCheck o de la integración del updater.

Continúa desde Getting Started

Si la configuración no funciona, usa Depuración antes de cambiar el code. La mayoría de los fallos se deben a un error de identidad, configuración de credenciales, permisos del OS, throttling en segundo plano o un mismatch en el ID de la app/package.