Inicio

@capgo/capacitor-notifications es el primer plugin de Capgo de primera parte para notificaciones de empuje nativas iOS y Android. Está construido para el panel de control de Capgo, el API público, el motor de análisis de dispositivos, estadísticas de campañas, actualizaciones de insignias y verificaciones de actualizaciones silenciosas 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 de Capgo API con acceso de escritura para la prueba de minteo en backend y envíos de API.
• La autoridad de empuje de la plataforma iOS y/o Android para la aplicación.
• @capgo/capacitor-updater si deseas actualizaciones de empuje silenciosas.

1. Configura Capgo Credenciales de Plataforma

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

Agrega una entrada de credenciales de plataforma por cada plataforma que desees soportar:

• Android - identificador de paquete de la aplicación y metadatos de proyecto de empuje de Android.
• iOS - identificador de paquete, identificador de equipo, identificador de clave y el metadato de clave de empuje de iOS que coincide.

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. Instala

Para 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

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

Instalación manual:

npm install @capgo/capacitor-notifications @capgo/capacitor-updater
npx 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 se inicie tu aplicación.

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' solo cuando desees que Capgo instale la actualización tan pronto como el actualizador pueda hacerlo de manera segura.

4. Probar una Prueba de Identidad

No coloque su Capgo API clave en la aplicación móvil. Su servidor debe pedir a Capgo una identityProof ventana de terminal

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

a la aplicación con su propia respuesta de sesión. identityProof 4. Probar una Prueba de Identidad

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 push nativo cambia.
• El usuario conectado cambia.
• Los etiquetas, atributos o consentimiento cambian.
• La aplicación no ha actualizado la registro durante mucho tiempo.

6. Agregar Escuchadores de Eventos

Registre los escuchadores durante el arranque de la aplicación para que los eventos de primer plano, abiertos 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()
  }
})

Llame siempre a 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 de la aplicación y active:

• Notificaciones Push
• Modos de fondo > Notificaciones remotas

Reenvíe 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:

npx cap sync ios

Utiliza 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 notificaciones de empuje de fondo.

8. Configuración de Android

Ejecuta:

npx cap sync android

Luego verifica:

• Tu credencial de plataforma Android está configurada en Capgo.
• El ID de paquete de la aplicación coincide con el ID de paquete utilizado para la configuración de empuje de plataforma.
• La aplicación solicita permiso de notificación en Android 13+ antes de esperar notificaciones visibles.
• La aplicación tiene un icono y una estrategia de canal de notificaciones que se ajusta a su marca.
• Prueba en un dispositivo físico o emulador con servicios de Google Play.

Crea un canal de notificación Android por defecto cuando tu aplicación inicie:

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 de empuje de Android. Mantén la política de icono de notificación, seguridad de red, extracción de datos y respaldo de la aplicación en la aplicación anfitriona.

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 una en la consola o llama /notifications/campaigns, luego envía 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 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. Habilitar Verificaciones Silenciosas de Actualizaciones

Las verificaciones silenciosas de actualizaciones conectan este plugin con @capgo/capacitor-updater.

En la aplicación:

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

En Capgo, habilite Actualizar a los usuarios en la configuración de notificaciones de la aplicación. Luego envíe una verificació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 las verificaciones de actualizaciones repetidas 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.
• El permiso es granted o el usuario ha aceptado la permisión de notificación.
• La plataforma registrada es android o ios.
• registrationChanged ¿O qué?
• dispara después de un refresco de token. notificationReceived.
• Un test de primer plano registra notificationOpened.
• Abriendo una notificación registra
• Los estadísticas de la consola muestran eventos programados y enviados, luego recibidos/abiertos cuando el dispositivo los informa. runUpdateCheck Silenciosos actualizaciones de verificación registran un resultado de

o la integración del actualizador.

Sección titulada “Sigue adelante desde Empezar” Depuración antes de cambiar la aplicación code. La mayoría de los errores se deben a la incompatibilidad de la prueba de identidad, la configuración de las credenciales de plataforma, el estado de permisos del sistema operativo, la limitación de fondo o la incompatibilidad del ID de aplicación/paquete.