Getting Started

@capgo/capacitor-notifications es el primer plugin de terceros de Capgo para notificaciones de empuje nativas de iOS y Android. Está diseñado para el panel de control de Capgo, el público API, el motor de análisis de dispositivos, estadísticas de campaña, actualizaciones de insignias y comprobaciones silenciosas de actualizaciones en vivo.

Requisitos

• Una aplicación 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 empuje de la plataforma iOS y/o Android para la aplicación.
• @capgo/capacitor-updater Si deseas comprobaciones silenciosas de actualizaciones.

1. Configura Capgo Credenciales de la Plataforma

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

Agregue una entrada de credenciales de plataforma para cada plataforma que desee soportar:

• Android - 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 shows the exact environment secret name that must exist in the API worker before the platform is marked configured. The dashboard stores metadata and the expected secret reference. The private credential itself stays in the worker environment.

2. Instale

For la configuración más rápida, ejecuta el Capgo CLI desde tu proyecto de aplicación:

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

La orden instala el paquete de notificaciones, guarda la configuración del plugin Capacitor, crea un pequeño archivo de ayuda y ejecuta Capacitor sincronización. Utiliza este camino para nuevas aplicaciones a menos que necesites conectar cada archivo manualmente.

Instalación manual:

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

Si no estás utilizando comprobaciones de actualizaciones Capgo silenciosas, puedes omitir @capgo/capacitor-updater.

3. Configurar El Plugin

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

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

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

Usar updateInstallMode: 'next' para descargar una actualización e instalarla en el próximo reinicio o ciclo de fondo. Usar updateInstallMode: 'set' solamente cuando desees 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 debería 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"
  }'

Devuelve el identityProof al aplicativo con tu propia respuesta de sesión.

5. Registra el Dispositivo

Registra 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 de nuevo cuando:

• El aplicación comienza.
• El token de notificación nativa cambia.
• El usuario conectado cambia.
• Los etiquetas, atributos o consentimiento cambian.
• La aplicación no ha actualizado la inscripción durante mucho tiempo.

6. Agregar Escuchadores de Eventos

Registre los oyentes durante el arranque de la aplicación 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 llamar finish() para notificaciones de fondo después de que se complete su trabajo. Mantenga el trabajo corto e idempotente.

7. Configuración de iOS

En Xcode, abra la pestaña de la aplicación 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 ejecute:

bunx cap sync ios

Utilice un dispositivo iOS físico para probar las notificaciones de fondo. Los simuladores son útiles para el trabajo de interfaz de usuario, pero no representan el comportamiento de producción de empuje de fondo.

8. Configuración de Android

Ejecutar:

bunx cap sync android

Luego verifique:

• 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 una estrategia de canal que se ajusta a su marca.
• Prueba en un dispositivo físico o emulador con servicios de Google Play.

Crea un canal Android predeterminado cuando se inicie tu aplicación:

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

9. Enviar una notificación de prueba

Usar Notificaciones > Enviar una prueba en Capgo, o llama al público API 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, crea en la consola o llama /notifications/campaignsluego envíe 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 servidor:

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. Habilita las comprobaciones de actualizaciones silenciosas

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

En la aplicación:

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

Habilite en Capgo Actualizar 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 el permiso de notificación.
• The plataforma registrada es android o ios.
• registrationChanged ocurre después de un refresco de tokens
• Un test de primer plano registra notificationReceived.
• Abriendo una notificación registra notificationOpened.
• Las estadísticas de la consola muestran eventos programados y enviados, luego recibidos/abiertos cuando el dispositivo los informa
• Silent update checks log a result from runUpdateCheck o la integración del actualizador

Sigue adelante desde Empezar

Si la configuración no funciona, utilice 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.