Getting Started

@capgo/capacitor-notifications es el plugin de primera parte de Capgo para notificaciones de empuje nativas de iOS y Android. Está construido 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 verificaciones silenciosas de actualizaciones en vivo.

El paquete se encuentra actualmente en vista previa privada. Capgo debe habilitar el acceso al paquete para su cuenta de npm antes de que funcione el comando de instalación.

Requisitos

• Una aplicación de Capacitor ya agregada a Capgo.
• Acceso a la pestaña de Notificaciones de la aplicación de Capgo.
• Una clave de Capgo API con acceso de escritura para la prueba de impresión de 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 verificaciones silenciosas de actualizaciones.

1. Configura las credenciales de la plataforma de Capgo

Abra la aplicación en Capgo, luego vaya a Notificaciones.

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

• Android - ID de paquete de la aplicación y metadatos de proyecto de notificación de Android.
• IOS - ID de paquete, ID de equipo, ID de clave y el metadato de la clave de notificación de 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 el proyecto de la 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 sincronización. Utiliza este camino para nuevas aplicaciones a menos que necesites cablear cada archivo manualmente.

Instalación manual:

npm install @capgo/capacitor-notifications @capgo/capacitor-updater
npx cap sync

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

3. Configurar 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',
})

Utiliza updateInstallMode: 'next' para descargar una actualización e instalarla en el próximo reinicio o ciclo de fondo. Utilice updateInstallMode: 'set' solo cuando desee 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 backend debe solicitar Capgo una identityProof después de que su 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 al la aplicación con su propia respuesta de sesión.

5. Registrar El Dispositivo

Registrese 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:

• La aplicación comienza.
• El token de notificación nativa cambia.
• El usuario conectado cambia.
• Cambian las etiquetas, atributos o consentimiento.
• La aplicación 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()
  }
})

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 el objetivo 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:

npx cap sync ios

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

8. Configuración de Android

Ejecutar:

npx cap sync android

Luego verifique:

• Su 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 notificaciones de plataforma.
• 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 coincide con su marca.
• Prueba en un dispositivo físico o emulador con servicios de Google Play.

Crear un canal de Android por defecto 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 Android de empuje. Mantenga la política de respaldo de la aplicación, extracción de datos, seguridad de red y política de icono de notificación en la aplicación anfitriona.

9. Enviar una notificación de prueba

Usar Notificaciones > Enviar de 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 una en la consola o llame al __CAPGO_KEEP_1__ del backend: /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 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 de actualizaciones silenciosas conectan este complemento con @capgo/capacitor-updater.

Dentro de 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 lo esperado externalId.
• Tiene permiso granted o el usuario ha aceptado permiso de notificación.
• La plataforma registrada es android o ios.
• registrationChanged se dispara después de un refresco de token.
• Un test de primer plano registra notificationReceived.
• Abrir una notificación registra notificationOpened.
• Los estadísticas de la consola muestran eventos programados y enviados, luego recibidos/abiertos cuando el dispositivo los informa.
• Actualizaciones silenciosas comprobaciones de registro un resultado de runUpdateCheck o la integración de actualizador.

Sigue adelante desde Getting Started

Si la configuración no funciona, utilice Depuración antes de cambiar la aplicación code. La mayoría de las fallas se deben a la incompatibilidad de la prueba de identidad, la configuración de credenciales de plataforma, el estado de permisos del sistema, la sobretensión de fondo, o la incompatibilidad de la ID de aplicación/paquete.