@capgo/capacitor-notifications

Panoramica

@capgo/capacitor-notifications collega un'app Capacitor alla pipeline di notifiche native di Capgo. La tua app registra un ID utente cliente firmato con Capgo, Capgo mantiene lo stato più recente dei dispositivi attivi in Cloudflare Analytics Engine, e puoi inviare notifiche, impostare badge, consultare le statistiche di consegna e avviare controlli silenziosi di live update di Capgo dalla dashboard di Capgo o tramite API.

Questa funzionalità è pensata per evitare una tabella dei dispositivi ad alta cardinalità in Capgo Postgres. Postgres memorizza solo dati del control plane a bassa cardinalità, come impostazioni dell'app, metadati delle credenziali di piattaforma, bozze di campagne, pianificazioni e record aggregati delle campagne. Lo stato dei dispositivi attivi e gli eventi di notifica sono righe append-only dell'Analytics Engine.

Supporto piattaforme

Piattaforma	Supporto	Note
iOS	Sì	APNs tramite Capgo
Android	Sì	FCM tramite Capgo
Web	No	Usa web push separatamente

Cosa memorizza Capgo

Dati	Dove si trova	Perché
Metadati delle credenziali della piattaforma	Capgo Postgres	Necessario per gestire setup e permessi dell'app.
Segreti privati della piattaforma	Ambiente Worker	Evita di salvare credenziali private in tabelle esposte ai clienti.
Bozze e impostazioni delle campagne	Capgo Postgres	Dati del control plane a bassa cardinalità.
Stato di registrazione dei dispositivi attivi	Motore Analytics di Cloudflare	Registro dispositivi attivi append-only a basso costo.
Eventi di notifica	Motore Analytics di Cloudflare	Statistiche economiche per eventi in coda, inviati, ricevuti, aperti, falliti e in background.

Modello di identità

Capgo non ti chiede di caricare una lista di utenti o gestire una tabella dei dispositivi.

• Il tuo backend conosce il vero ID utente del cliente.
• Il tuo backend richiede a Capgo un breve identityProof.
• L'app si registra con externalId e quella prova dopo il successo della tua autenticazione utente.
• Capgo genera chiavi interne deterministiche per il destinatario e l'installazione nativa.
• Inviando allo stesso externalId ritrova nuovamente i dispositivi attivi dell'utente.

Ti permette di cercare i dispositivi di un utente, impostare i badge e gestire campagne di notifiche senza dover salvare righe di notifica per ogni dispositivo in Capgo Postgres.

Funzionalità principali

• Registra i dispositivi associandoli a un ID utente esterno autenticato.
• Aggiorna tag, attributi, consensi e lo stato del token all'avvio dell'app o al cambio del token.
• Ricevi notifiche in foreground tramite JavaScript.
• Monitora gli eventi di ricezione e apertura delle notifiche.
• Gestisci le notifiche dati in background.
• Imposta, cancella e incrementa i badge dell'app.
• Crea i canali di notifica su Android.
• Invia notifiche singole, notifiche di campagna, aggiornamenti badge e controlli silenziosi di aggiornamento.
• Attiva @capgo/capacitor-updater da una notifica silenziosa.

Statistiche

Capgo scrive gli eventi delle notifiche su Cloudflare Analytics Engine per mantenere i costi delle stats del dashboard contenuti:

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

Le statistiche sono segnali operativi, non un registro permanente per ogni destinatario. La retention dell'Analytics Engine richiede che i dispositivi attivi aggiornino periodicamente la registrazione.

Pubblico API

Metodo	Descrizione
configure	Configura l'app ID di Capgo, l'host di API e il comportamento di integrazione dell'updater.
register	Registra l'installazione corrente con un ID utente esterno del cliente.
setExternalId	Cambia l'ID utente esterno del cliente dopo il login o il cambio account.
setTags	Sostituisce i tag usati per il targeting del pubblico.
setBadge	Imposta il badge dell'app nativa.
clearBadge	Cancella il badge dell'app nativa.
incrementBadge	Incrementa il badge dell'app nativa.
enableUpdaterIntegration	Abilita la gestione silenziosa del controllo aggiornamenti tramite @capgo/capacitor-updater.
runUpdateCheck	Esegue manualmente l'integrazione dell'updater per i test.
trackReceived	Scrive manualmente un evento di ricezione.
trackOpened	Scrive manualmente un evento di apertura.
addListener('notificationReceived')	Viene attivato quando ricevi una notifica mentre JavaScript è attivo.
addListener('notificationOpened')	Viene attivato quando un utente apre una notifica.
addListener('backgroundNotification')	Viene attivato per le notifiche dati in background e espone finish().
addListener('registrationChanged')	Viene attivato quando il token push nativo cambia.

Garanzie di consegna

Il push nativo è at-least-once. Una campagna può essere ritentata e un dispositivo può ricevere un duplicato se la piattaforma accetta un messaggio ripetuto. Usa i collapse ID per i controlli di aggiornamento e rendi idempotente il lavoro in background.

Le notifiche in background su iOS sono best-effort. Il sistema operativo può limitare o saltare l'esecuzione in background in base a batteria, comportamento dell'utente, stato di force-quit e policy di sistema. Non affidarti alle notifiche silenziose per scadenze rigide.

Continua da @capgo/capacitor-notifications

Se stai usando @capgo/capacitor-notifications per pianificare i messaggi push, collegalo a Per iniziare for setup, Debug per il troubleshooting, @capgo/capacitor-updater per i controlli degli aggiornamenti silenziosi, e Directory dei plugin di Capgo per altri plugin nativi.