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 de mise à jour silencieuse en temps réel.

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 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 vérification push silencieuses.

1. Configurez 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 - 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 dashboard stocke les métadonnées et la référence secrète attendue. Le crédentials 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 connecter chaque fichier manuellement.

Installation manuelle :

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

Si vous n'utilisez pas les contrôles de mise à jour silencieuse Capgo, 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 lors du prochain redémarrage ou cycle de fond d'arrière-plan. Utilisez 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éer une preuve d'identité

N'insérez pas votre clé Capgo API dans l'application mobile. Votre serveur 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"
  }'

Retourner la identityProof à l'application avec votre propre réponse de session.

5. Inscrivez le Dispositif

Inscrivez-vous 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 étiquettes, 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 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()
  }
})

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.
• Votre 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 l’API public de votre serveur :

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 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 contrôles de mise à jour silencieux

Les contrôles de mise à jour silencieux connectent ce plugin avec @capgo/capacitor-updater.

Dans l'application :

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

Dans Capgo, activez Mettre à jour les utilisateurs par push dans les paramètres de notifications de l'application. Ensuite, effectuez 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 de validation

• L'application apparaît dans Capgo pour la recherche de destinataires attendus pour externalId.
• L'autorisation est granted ou l'utilisateur a accepté la permission de notification.
• La plateforme enregistrée est android ou ios.
• registrationChanged ou le gestionnaire de mise à jour intégré.
• se déclenche après une mise à jour de jeton. notificationReceived.
• Un test en avant-plan enregistre notificationOpened.
• Ouvrir une notification enregistre
• Les statistiques du tableau de bord montrent les événements en attente et envoyés, puis reçus/ouverts lorsque le dispositif les signale. runUpdateCheck Silent update checks enregistrent un résultat de

ou le gestionnaire de mise à jour intégré.

Si la mise en place ne fonctionne pas, utilisez Débogage Avant de modifier votre application code. La plupart des erreurs sont causées par un désaccord d'identification, la configuration des informations de plateforme, l'état des permissions du système d'exploitation, la surcharge de fond, ou un désaccord d'ID d'application/pack.