Commencer

@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'engrenage d'analyse des appareils, les statistiques de campagne, les mises à jour de badge et les vérifications silencieuses de mise à jour en direct.

Exigences

• Une application Capacitor déjà ajoutée à Capgo.
• L'accès à la rubrique Notifications de l'application Capgo.
• Une clé Capgo API avec accès en écriture pour la preuve de signature backend 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 mise à jour push silencieuses.

1. Configurez les Capgo Clés de Plateforme.

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

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

• Android - identifiant de package de l'application et métadonnées de projet de push Android.
• iOS - identifiant de bundle, identifiant de l'équipe, identifiant de clé et les métadonnées de clé de push iOS correspondantes.

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 secrète attendue. Le credencial privé reste dans l'environnement du worker.

2. Installez

Pour une 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

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

Installation manuelle :

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

Si vous n'utilisez pas les vérifications de mise à jour Capgo silencieuses, vous pouvez omettre @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',
})

Utiliser updateInstallMode: 'next' pour télécharger une mise à jour et l'installer à la prochaine redémarrage ou cycle de fond. Utilisez updateInstallMode: 'set' seulement lorsque vous voulez que Capgo installe la mise à jour dès que le metteur à jour peut le faire de manière sûre.

4. Créer une preuve d'identité

N'insérez pas votre Capgo API clé dans l'application mobile. Votre backend devrait demander à Capgo une identityProof après 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"
  }'

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

5. Enregistrez 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)

Appeler register context

• Appeler
• à nouveau lorsque :
• Le lancement de l'application.
• Le jeton de push natif change.
• L'utilisateur connecté change.

Les balises, attributs ou les consentements changent.

Enregistrez les écouteurs pendant le démarrage de l'application afin que les événements de premier plan, 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()
  }
})

Appel toujours 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

Transmettre les notifications à distance à partir de 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, exécutez :

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

npx cap sync android

Vérifiez ensuite :

• Votre credencial de plateforme Android est configurée dans Capgo.
• L'ID de package de l'application correspond à l'ID de package utilisé pour la configuration de push de plateforme.
• La permission de notification Android 13+ est demandée avant d'attendre des notifications visibles.
• L'application a un icône de notification et 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 l'application de sauvegarde, 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 de 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/campaigns, puis envoyez à 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()

À partir de votre back-end :

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 Silencieuses

Les vérifications de mises à jour silencieuses connectent ce plugin avec @capgo/capacitor-updater.

Dans l'application :

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

Dans Capgo, activez Mise à jour Push vers les utilisateurs dans les paramètres de notifications de l'application. Ensuite, envoyez une vérification de mise à jour depuis le tableau de bord 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 ID de collapsage afin que les vérifications de mise à jour se remplacent les unes les autres lorsque le support de comportement de collapsage est pris en charge par la plateforme.

Liste de vérification

• L'application apparaît dans Capgo rechercheur de destinataires attendus pour le externalId.
• L'autorisation est granted ou l'utilisateur a accepté la permission de notification.
• La plateforme enregistrée est android ou ios.
• registrationChanged ou l'utilisateur a accepté la permission de notification.
• La plateforme enregistrée est notificationReceived.
• ou notificationOpened.
• ou l'utilisateur a accepté la permission de notification.
• La plateforme enregistrée est runUpdateCheck ou

La mise à jour silencieuse vérifie un résultat de

Si la configuration ne fonctionne pas, utilisez Débogage avant de modifier votre application code. La plupart des erreurs sont causées par un manquement de preuve d'identité, la configuration des informations de plateforme, l'état des permissions du système d'exploitation, la surcharge de fond, ou un manquement d'ID d'application/paquet.