Prise en main

@capgo/capacitor-notifications est le premier plugin Capgo natif pour les notifications push iOS et Android. Il est conçu pour le dashboard de Capgo, l'API public, le registre d'appareils de l'Analytics Engine, les stats de campagne, les mises à jour de badges et les vérifications silencieuses de live update.

Prérequis

• Une application Capacitor déjà ajoutée à Capgo.
• Accès à l'onglet Notifications de l'application Capgo.
• Une clé API Capgo avec accès en écriture pour le minting de preuves backend et les envois API.
• Autorité push pour la plateforme iOS et/ou Android de l'application.
• @capgo/capacitor-updater if you want silent push update checks.

Démarrage rapide

import { CapacitorNotifications } from '@capgo/capacitor-notifications';
await CapacitorNotifications.register({ customerUserId: 'signed-id' });

Erreurs courantes

• Utilisez des valeurs customerUserId signées provenant de votre backend.
• Demandez l'autorisation de notification avant l'enregistrement.
• Vérifiez les identifiants Capgo dans le dashboard.

1. Configurer les identifiants de la plateforme Capgo

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

Ajoutez une entrée d'identifiants pour chaque plateforme que vous voulez prendre en charge :

• Android - l'ID du package de l'app et les métadonnées du projet de push Android.
• iOS - le bundle ID, le team ID, le key ID et les métadonnées de la clé de push iOS correspondante.

Capgo affiche le nom exact du secret d'environnement qui doit exister dans le worker API avant que la plateforme ne soit marquée comme configurée. Le dashboard stocke les métadonnées et la référence au secret attendu. L'identifiant privé lui-même reste dans l'environnement du worker.

2. Installer

Pour une configuration rapide, lancez le Capgo CLI depuis votre projet d'app :

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

La commande installe le package de notifications, enregistre la config du plugin Capacitor, crée un petit fichier d'aide et exécute la sync Capacitor. Utilisez cette méthode pour les nouvelles apps, sauf si vous devez câbler chaque fichier à la main.

Installation manuelle :

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

Si vous n'utilisez pas de vérifications silencieuses de Capgo update, vous pouvez omettre @capgo/capacitor-updater.

3. Configurer le plugin

Configurez le plugin une seule fois au démarrage de votre application.

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

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

Utiliser updateInstallMode: 'next' pour télécharger une mise à jour et l'installer au prochain redémarrage ou cycle en arrière-plan. Utilisez updateInstallMode: 'set' uniquement lorsque vous voulez que Capgo installe la mise à jour dès que l'updater peut le faire en toute sécurité.

4. Créer une preuve d'identité

N'intégrez pas votre clé Capgo API dans l'application mobile. Votre backend doit demander à Capgo une identityProof une fois que votre propre authentification utilisateur a réussi.

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

Retournez le identityProof à l'application avec votre propre réponse de session.

5. Enregistrer l'appareil

N'enregistrez l'appareil qu'une fois que 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)

Appelez register à nouveau lorsque :

• L'application démarre.
• Le token push natif change.
• L'utilisateur connecté change.
• Les tags, attributs ou le consentement changent.
• L'application n'a pas rafraîchi son enregistrement depuis longtemps.

6. Ajouter des écouteurs d'événements

Enregistrez les écouteurs au démarrage de l'application pour que les événements foreground, opened et background soient visibles depuis 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()
  }
})

Appelez toujours finish() pour les notifications en arrière-plan une fois votre tâche terminée. Gardez ce travail court et idempotent.

7. Configuration iOS

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

• Notifications push
• Modes d'arrière-plan > Notifications distantes

Transférez les notifications distantes depuis 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)
}

Ensuite, lancez :

bunx cap sync ios

Utilisez un appareil iOS physique pour tester les notifications en arrière-plan. Les simulateurs sont utiles pour l'UI, mais ne reflètent pas le comportement réel des notifications push en arrière-plan.

8. Configuration Android

Exécutez :

bunx cap sync android

Vérifiez ensuite :

• Votre identifiant de plateforme Android est configuré dans Capgo.
• L'ID de package de l'application correspond à celui utilisé pour la configuration push de la plateforme.
• La permission de notification Android 13+ est demandée avant de pouvoir afficher des notifications.
• L'application dispose d'une icône de notification et d'une stratégie de canaux qui correspondent à votre marque.
• Vous testez sur un appareil physique ou un émulateur avec les services Google Play.

Créez un canal Android par défaut au démarrage de votre application :

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. Gérez la sauvegarde de l'app, l'extraction de données, la sécurité réseau et la politique d'icône de notification dans l'app hôte.

9. Envoyer une notification de test

Utiliser Notifications > Test d'envoi dans Capgo, ou appelez la méthode publique 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 dashboard ou appelez /notifications/campaigns, puis envoyez à un ID externe, un tag, un segment ou une audience globale.

10. Configurer les badges

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

Depuis 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 mise à jour silencieuses

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

In the app:

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

Dans Capgo, activez Envoyer une mise à jour push aux utilisateurs dans les paramètres de Notifications de l'application. Puis, lancez une vérification de mise à jour depuis le dashboard ou 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 collapse ID afin que les vérifications de mise à jour répétées se remplacent mutuellement lorsque la plateforme supporte le comportement de collapse.

Checklist de validation

• L'application apparaît dans la recherche de destinataire Capgo pour la externalId.
• permission est granted ou l'utilisateur a accepté la permission de notification.
• La plateforme enregistrée est android ou ios.
• registrationChanged se déclenche après un refresh du token.
• Un test au premier plan logue notificationReceived.
• Ouverture d'un log de notification notificationOpened.
• Les statistiques du dashboard affichent les événements en attente et envoyés, puis reçus/ouverts lorsque l'appareil les rapporte.
• Silent update checks log a result from runUpdateCheck ou de l'intégration de l'updater.

Continuer depuis Getting Started

Si la configuration ne fonctionne pas, utilisez Débogage avant de modifier l'code de l'app. La plupart des échecs sont causés par une erreur de preuve d'identité, la configuration des identifiants de plateforme, l'état des permissions de l'OS, le throttling en arrière-plan ou une discordance d'ID d'app/package.