Début

@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.

Le package est actuellement en prévision privée. Capgo doit activer l'accès au package pour votre compte npm avant que la commande d'installation fonctionne.

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 vérifications de mise à jour push silencieuses.

1. Configurez les informations de plateforme Capgo

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

Ajoutez une entrée de données d'identification de plateforme pour chaque plateforme que vous souhaitez prendre en charge :

• 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 la clé de push iOS correspondante.

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

2. Installer

Pour un démarrage le 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 ne utilisez pas les vérifications de mise à jour silencieuses 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',
})

Utilisez updateInstallMode: 'next' pour télécharger une mise à jour et l'installer à la prochaine redémarrage ou cycle de fond. updateInstallMode: 'set' Utilisez uniquement lorsque vous souhaitez 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é

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

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

5. Enregistrer 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 à nouveau lorsque :

• L'application démarre.
• Le jeton de notification native change.
• Le connecté utilisateur change.
• Les balises, attributs ou consentement changent.
• L'application n'a pas rafraîchi la mise à jour de la registration depuis longtemps.

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

Enregistrer les écouteurs pendant le démarrage de l'application afin que les événements de foreground, ouverts et de fond soient visibles à 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 que votre travail est terminé. 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 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 la mise en production des notifications de push de fond.

8. Configuration Android

Exécuter :

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 la mise en push de la 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 é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. Conservez la sauvegarde de l'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/campaignsEnvoie ensuite à un ID externe, une étiquette, un segment ou un public ciblé.

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 silencieuses

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

Dans l'application :

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

In Capgo, activez Mise à jour 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 système le supporte.

Liste de vérification

• L'application apparaît dans Capgo rechercheur de destinataires pour le résultat attendu externalId.
• L'autorisation est granted ou l'utilisateur a accepté la permission de notification.
• L'application est enregistrée sur android ou ios.
• registrationChanged s'active après un rafraîchissement 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 périphérique les signale.
• Vérifications de mise à jour silencieuses enregistrent un résultat de runUpdateCheck ou l'intégration de l'actualiseur.

Continuez de l'étape de démarrage

Si la configuration ne fonctionne pas, utilisez Débogage avant de modifier l'application code. La plupart des échecs sont causés par un désaccord de preuve d'identité, une configuration de crédentials de plateforme, un état de permission du système d'exploitation, un étranglement de fond, ou un désaccord d'ID d'application/paquet.