Getting Started

@capgo/capacitor-notifications es el primer plugin de Capgo para notificaciones push nativas de iOS y Android. Está diseñado para Capgo’s panel de control, publico API, Motor de análisis de dispositivos, estadísticas de campañas, actualizaciones de iconos y verificaciones silenciosas de actualizaciones en vivo.

Requisitos

• A una aplicación de Capacitor ya agregada a Capgo.
• Acceso a la pestaña de Notificaciones de la aplicación Capgo.
• Una clave Capgo API con acceso de escritura para la creación de pruebas de backend y API.
• Autoridad de notificación para iOS y/o Android para la aplicación.
• @capgo/capacitor-updater Si deseas actualizaciones de notificaciones silenciosas.

1. Configura las credenciales de plataforma de Capgo.

Abre la aplicación en Capgo, luego ve a Notificaciones.

Agregar una entrada de credenciales de plataforma para cada plataforma que desees soportar:

• Androide - app package ID and Android push project metadata.
• iOS ID de paquete, ID de equipo, ID de clave y la metadata de la clave de push iOS correspondiente.

Capgo muestra el nombre exacto del secreto de entorno que debe existir en el trabajador API antes de que la plataforma se marque configurada. La consola almacena metadatos y la referencia secreta esperada. El credencial privada permanece en el entorno del trabajador.

2. Instalar

Para la configuración más rápida, ejecute el Capgo CLI desde su proyecto de aplicación:

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

El comando instala el paquete de notificaciones, guarda la configuración del plugin Capacitor, crea un pequeño archivo de ayuda y ejecuta Capacitor sincronizar. Utilice este camino para nuevas aplicaciones a menos que necesite cablear cada archivo manualmente.

Instalación manual:

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

If you are not using silent Capgo checks, you can omit @capgo/capacitor-updater.

3. Configura El Plugin

Configura el plugin una vez que tu aplicación arranca.

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 de fondo. Usa updateInstallMode: 'set' solamente cuando quieras que Capgo instale la actualización tan pronto como el actualizador pueda hacerlo de manera segura.

4. Crea Una Prueba De Identidad

No coloques tu Capgo API clave en la aplicación móvil. Tu backend debe pedir a Capgo una identityProof después de que tu autenticación de usuario tenga éxito.

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"
  }'

Devolver el identityProof devolverlo a la aplicación con tu propia respuesta de sesión.

5. Registrar el dispositivo

Registre solo después de saber qué usuario de cliente está conectado.

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)

Llamar register nuevamente cuando:

• de nuevo cuando:
• El aplicativo comienza a ejecutarse.
• El usuario conectado cambia.
• Se cambian etiquetas, atributos o consentimiento.
• No se ha actualizado la inscripción del app durante mucho tiempo.

6. Agregar Escuchadores de Eventos

Registre escuchadores durante el arranque del app para que los eventos de primer plano, abierto y de fondo estén visibles en JavaScript.

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()
  }
})

Siempre llame finish() para notificaciones de fondo después de que su trabajo esté hecho. Mantenga el trabajo corto e idempotente.

7. Configuración de iOS

En Xcode, abra el objetivo del app y habilite:

• Notificaciones Push
• Modos de fondo > Notificaciones remotas

Enviar 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

Utilice un dispositivo iOS físico cuando esté probando notificaciones de fondo. Los simuladores son útiles para el trabajo de interfaz de usuario pero no representan el comportamiento de producción de notificaciones de fondo.

8. Configuración de Android

Ejecuta:

bunx cap sync android

Luego verifica:

• Su credencial de plataforma Android está configurada en Capgo.
• The app package ID matches the package ID used for platform push setup.
• Se solicita permiso de notificación de Android 13+ antes de esperar notificaciones visibles.
• La aplicación tiene un icono de notificación y estrategia de canal que se ajusta a su marca.
• Pruebas en un dispositivo físico o emulador con servicios de Google Play.

Crear un canal de Android por defecto cuando la aplicación arranca:

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. Mantenga la política de iconos de notificación, la seguridad de red, la extracción de datos y la copia de seguridad de la aplicación en la aplicación host.

Sección titulada “9. Enviar una notificación de prueba”

Utilice Notificaciones > Enviar prueba en Capgo, o llame al público API desde su 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, cree uno en la consola o llame /notifications/campaignsy envíelo a un ID externo, etiqueta, segmento o audiencia de difusión.

10. Establecer Badges

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

Desde su 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. Habilitar Verificaciones Silenciosas de Actualizaciones

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

En la aplicación:

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

En Capgo, habilite Enviar actualización a los usuarios En la configuración de Notificaciones del app. Luego, realiza una comprobación de actualizaciones desde la consola 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 utiliza un ID de colapso para que los controles de actualización repetidos se reemplacen entre sí cuando el plataforma admite el comportamiento de colapso.

Lista de Verificación de Validación

• La aplicación aparece en Capgo búsqueda de destinatarios para el esperado externalId.
• La permiso es granted o el usuario ha aceptado la permiso de notificación.
• La plataforma registrada es android o ios.
• registrationChanged Las preguntas de alternativas
• Un registro de prueba en primer plano notificationReceived.
• Un test de frente registra notificationOpened.
• Estadísticas de la consola muestran eventos programados y enviados, luego recibidos/abiertos cuando el dispositivo los informa.
• Silent update checks registran un resultado de runUpdateCheck o la integración del actualizador.

Sigue adelante desde Inicio

Si la configuración no funciona, utiliza Depuración before changing app code. Most failures are caused by identity proof mismatch, platform credential setup, OS permission state, background throttling, or app/package ID mismatch.