Inicio

@capgo/capacitor-notifications es el primer plugin de Capgo de primera parte para notificaciones de empuje nativas iOS y Android. Está diseñado para Capgo’s panel de control, publico API, Motor de análisis de dispositivos, estadísticas de campaña, actualizaciones de insignia y verificaciones 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 de Capgo API con acceso de escritura para la impresión de pruebas de backend y envíos de API.
• Autenticación de empuje de plataforma iOS y/o Android para la aplicación.
• @capgo/capacitor-updater si deseas comprobaciones de actualizaciones silenciosas de empuje.

1. Configura Capgo Credenciales de la Plataforma

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

Agrega una entrada de credenciales de plataforma para 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 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' 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 después de que su autenticación de usuario propia haya tenido é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 su 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 ¿Cuándo?

• Cuando el app arranca.
• Cuando cambia el token de notificación nativa.
• Cuando cambia el usuario conectado.
• Cuando cambian las etiquetas, atributos o consentimiento.
• Cuando el app no ha actualizado la registro durante mucho tiempo.

6. Agregar Escuchadores de Eventos

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

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

• 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 de Android 13+ solicita permiso de notificación antes de esperar notificaciones visibles.
• La aplicación tiene un icono y una estrategia de canal de notificaciones que se ajustan a su marca.
• Prueba en un dispositivo físico o emulador con servicios de Google Play.

Crear un canal de notificaciones Android predeterminado cuando se inicie la 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 de empuje de Android. Mantenga la política de icono 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 anfitriona.

9. Enviar una notificación de prueba

Usar Notificaciones > Enviar una prueba en Capgo, o llame al público API desde su servidor:

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/campaignsluego 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.

In 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 de la aplicación. Luego envíe una comprobación de actualización 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 comprobaciones de actualización 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.
• La autorización es granted o el usuario ha aceptado la permisión de notificaciones.
• 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 Silent update checks registra un resultado de

o la integración del actualizador.

Continúa desde Empezar: paso siguiente es… Depuración antes de cambiar la aplicación code. La mayoría de los errores se deben a una 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 la aplicación/paquete.