@capgo/capacitor-notifications

Aperçu

@capgo/capacitor-notifications connecte une application Capacitor au pipeline de notifications natif de Capgo. Votre application enregistre un ID utilisateur client signé auprès de Capgo, Capgo conserve l'état de l'appareil actif le plus récent dans le moteur Cloudflare Analytics, et vous pouvez envoyer des notifications, définir des badges, inspecter les statistiques de livraison et déclencher des vérifications silencieuses de Capgo live-update depuis le dashboard Capgo ou API.

Cette fonctionnalité est conçue pour éviter une table de dispositifs de notification à haute cardinalité dans le Postgres de Capgo. Postgres ne stocke que des données de plan de contrôl’à faible cardinalité, telles que les paramètres de l'application, les métadonnées d'identification de plateforme, les brouillons de campagne, les plannings et les enregistrements de campagne agrégés. L'état des appareils actifs et les événements de notification sont des lignes en mode append-only dans l'Analytics Engine.

Support des plateformes

Plateforme	Support	Notes
iOS	Oui	APNs via Capgo
Android	Oui	FCM via Capgo
Le Web	Non	Utiliser le web push séparément

Ce que Capgo stocke

Données	Lieu de stockage	Pourquoi
Métadonnées des identifiants de plateforme	Capgo Postgres	Needed to manage app setup and permissions.
Secrets privés de la plateforme	Environnement du Worker	Évite de stocker des identifiants privés dans des tables exposées aux clients.
Brouillons et paramètres de campagne	Capgo Postgres	Données du plan de contrôl’à faible cardinalité.
État d'enregistrement des appareils actifs	Cloudflare Analytics Engine	Registre d'appareils actifs peu coûteux en mode append-only.
Événements de notification	Moteur d'analyse Cloudflare	Des stats économiques pour les événements mis en file d'attente, envoyés, reçus, ouverts, échoués et en arrière-plan.

Modèle d'identité

Capgo ne vous demande pas d'envoyer une liste d'utilisateurs ou de gérer une table d'appareils.

• Votre backend connaît l'ID utilisateur réel du client.
• Votre backend demande à Capgo un jeton à courte durée de vie identityProof.
• L'application s'enregistre avec externalId et cette preuve une fois votre propre authentification utilisateur réussie.
• Capgo génère des clés internes déterministes pour le destinataire et l'installation native.
• L'envoi vers le même externalId retrouve à nouveau les appareils actifs de l'utilisateur.

Cela vous permet de rechercher les appareils d'un utilisateur, de définir des badges et de cibler des campagnes de notifications sans stocker de lignes de notification par appareil dans Capgo Postgres.

Fonctionnalités clés

• Enregistrer les appareils avec un ID utilisateur externe authentifié.
• Refresh tags, attributes, consent, and token state on app start or token changes.
• Recevoir les notifications au premier plan en JavaScript.
• Suivre les événements de réception et d'ouverture des notifications.
• Gérer les notifications de données en arrière-plan.
• Définir, effacer et incrémenter les badges de l'app.
• Créer des canaux de notification Android.
• Send one-off notifications, campaign notifications, badge updates, and silent update checks.
• Déclencher @capgo/capacitor-updater depuis une notification silencieuse.

Stats

Capgo écrit les événements de notification dans le moteur Analytics de Cloudflare pour garder les stats du dashboard économiques :

• queued
• sent
• provider_accepted
• received
• opened
• failed
• permission_changed
• background_started
• background_finished

Les stats sont des signaux opérationnels, pas un registre permanent par destinataire. La rétention d'Analytics Engine implique que les appareils actifs doivent renouveler leur enregistrement périodiquement.

API public

Méthode	Description
configure	Définit l'ID d'application Capgo, l'hôte API et le comportement d'intégration de l'updater.
register	Enregistre l'installation actuelle pour un ID utilisateur client externe.
setExternalId	Modifie l'ID utilisateur client externe après une connexion ou un changement de compte.
setTags	Remplace les tags utilisés pour le ciblage d'audience.
setBadge	Définit le badge de l'application native.
clearBadge	Efface le badge de l'application native.
incrementBadge	Incrémente le badge de l'application native.
enableUpdaterIntegration	Permet de gérer les vérifications de mise à jour silencieuses via @capgo/capacitor-updater.
runUpdateCheck	Exécute manuellement l'intégration de l'updater pour les tests.
trackReceived	Écrit manuellement un événement de réception.
trackOpened	Écrit manuellement un événement d'ouverture.
addListener('notificationReceived')	Se déclenche lorsqu'une notification est reçue pendant que le JavaScript est actif.
addListener('notificationOpened')	Se déclenche lorsqu'un utilisateur ouvre une notification.
addListener('backgroundNotification')	Se déclenche pour les notifications de données en arrière-plan et expose finish().
addListener('registrationChanged')	Se déclenche lorsque le token push natif change.

Garanties de livraison

Le push natif est de type « at-least-once ». Une campagne peut être réessayée, et un appareil peut recevoir un doublon si la plateforme accepte un message répété. Utilisez des collapse IDs pour les vérifications de mise à jour et rendez vos traitements en arrière-plan idempotents.

Les notifications en arrière-plan iOS sont de type « best-effort ». L'OS peut limiter ou ignorer l'exécution en arrière-plan selon la batterie, le comportement de l'utilisateur, l'état de fermeture forcée et la politique du système. Ne comptez pas sur les notifications silencieuses pour des échéances strictes.

Continuer à partir de @capgo/capacitor-notifications

Si vous utilisez @capgo/capacitor-notifications pour planifier vos messages push, connectez-l’avec Prise en main for setup, Débogage pour le dépannage, @capgo/capacitor-updater pour les vérifications silencieuses de mise à jour, et Capgo Répertoire des plugins pour les autres plugins natifs.