Prise en main

@capgo/capacitor-notifications est le plugin tiers Capgo pour les notifications push natives iOS et Android. Il est conçu pour le tableau de bord de Capgo, le public API, l'Engine de statistiques, le registre des appareils, les mises à jour de badges et les vérifications de mise à jour en direct silencieuses.

Exigences

• Une application Capacitor déjà ajoutée à Capgo.
• D'accès à la rubrique Notifications de l'application Capgo.
• Une clé Capgo API avec accès en écriture pour la preuve de signature et les envois API.
• L'autorité de push pour les plateformes iOS et/ou Android de l'application.
• @capgo/capacitor-updater Si vous souhaitez des mises à jour de push silencieuses.

1. Configure les Capgo Identifiants de la Plateforme

Ouvrez l'application dans Capgo, puis allez à Notifications.

Ajoutez une entrée de crédentials de plateforme pour chaque plateforme que vous souhaitez supporter :

• Android - ID de l'application et les métadonnées du projet de push Android.
• iOS - ID de l'application, ID d'équipe, ID de clé et la clé de push iOS correspondante.

Capgo affiche le nom exact du secret d'environnement qui doit exister dans l’API worker avant que la plateforme soit marquée comme configurée. Le tableau de bord stocke les métadonnées et la référence attendue du secret. Le crédential privé reste dans l'environnement du worker.

2. Installer

For la mise en place la plus rapide, exécutez le Capgo CLI depuis votre projet d'application :

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

Le commandement installe le package de notification, enregistre la configuration du plugin Capacitor, crée un petit fichier d'aide et exécute Capacitor synchronisation. Utilisez ce chemin pour les nouvelles applications, à moins que vous n'ayez besoin de relier chaque fichier manuellement.

Installation manuelle :

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

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

3. Configurer le plugin

Configurez le plugin une fois que votre application démarre.

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

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

Utilisez updateInstallMode: 'next' pour télécharger une mise à jour et l'installer lors du prochain redémarrage ou cycle de fond. updateInstallMode: 'set' seulement lorsque vous voulez que Capgo installe la mise à jour dès que l'actualiseur peut le faire en toute sécurité.

4. Créez une preuve d'identité

Ne pas insérer votre clé Capgo API dans l'application mobile. Votre serveur backend devrait demander Capgo un identityProof après votre propre authentification utilisateur réussie.

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

Retourner le identityProof ajoutez votre propre réponse de session à l'application.

5. Inscrivez le Dispositif

Enregistrez uniquement lorsque vous savez quel utilisateur client est connecté.

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)

context register Appeler

• L'application démarre.
• Le jeton de notification push natif change.
• Le lancement de l'application.
• Le jeton de push natif change.
• L'application n'a pas mis à jour l'enregistrement depuis très longtemps.

Les balises, attributs ou les consentements changent.

Enregistrez les écouteurs pendant le démarrage de l'application afin que les événements de fond, ouverts et de fond soient visibles au 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()
  }
})

Toujours appeler finish() pour les notifications de fond après avoir terminé votre travail. Gardez le travail court et idempotent.

7. Configuration iOS

Dans Xcode, ouvrez la cible de l'application et activez :

• Notifications Push
• Modes de fond > Notifications à distance

Transmettez les notifications à distance 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)
}

Then run:

bunx cap sync ios

Utilisez un appareil iOS physique pour tester les notifications de fond. Les simulateurs sont utiles pour le travail de l'interface utilisateur mais ne représentent pas le comportement de push de fond en production.

8. Configuration Android

Exécutez :

bunx cap sync android

Vérifiez ensuite :

• Votre credencial de plateforme Android est configurée dans Capgo.
• The app package ID matches the package ID used for platform push setup.
• La permission de notification Android 13+ est demandée avant d'attendre des notifications visibles.
• L'application dispose d'un icône de notification et d'une stratégie de canal qui correspondent à votre marque.
• Vous testez sur un appareil physique ou un émulateur avec Google Play services.

Créez un canal Android par défaut lorsque votre application démarre :

await CapgoNotifications.configure({ appId: 'com.example.app' })

await CapgoNotifications.register({
  externalId: currentUser.id,
  identityProof: currentUser.capgoNotificationProof,
  consent: true,
})

Le plugin déclare le service de messagerie push Android. Gardez la sauvegarde d'application, l'extraction de données, la sécurité réseau et la politique d'icône de notification dans l'application hôte.

9. Envoyer une notification de test

Utilisez Notifications > Envoyer un test dans Capgo, ou appelez le public API depuis votre 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" }
    }
  }'

Pour une campagne, créez-la dans le tableau de bord ou appelez /notifications/campaignspuis envoyez-l’à un ID externe, une étiquette, un segment ou un public de diffusion.

10. Définir les badges

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

De votre 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. Activer les Vérifications de Mises à Jour en Arrière-plan

Vérifications silencieuses de mise à jour s'associent à ce plugin @capgo/capacitor-updater.

In the app:

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

Activez-le dans Capgo Envoyez une mise à jour aux utilisateurs in the app’s Notifications settings. Then send an update check from the dashboard or 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 notification est silencieuse et utilise un ID de collapsage afin que les vérifications de mise à jour répétées se remplacent mutuellement lorsque le plateforme prend en charge le comportement de collapsage.

Liste de vérification

• L'application apparaît dans Capgo rechercheur de destinataires attendus externalId.
• L'autorisation est granted ou l'utilisateur a accepté la permission de notification.
• La plateforme enregistrée est android ou ios.
• registrationChanged Lors d'une mise à jour de jeton,
• Un test en avant-plan enregistre notificationReceived.
• L'ouverture d'une notification enregistre notificationOpened.
• Les statistiques du tableau de bord affichent les événements en attente et envoyés, puis reçus/ouverts lorsque le dispositif les signale.
• Silent update checks log a result from runUpdateCheck ou l'intégration de l'actualiseur.

Continuez de la section « Continuez de Getting Started »

Si la mise en place ne fonctionne pas, utilisez Debugging 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.