Debug

Usa questa checklist se una notifica non viene registrata, non arriva, non viene visualizzata o non aggiorna le statistiche di Capgo.

Parti dal Device Record

Prima di fare il debug di code nativo, conferma che Capgo veda il dispositivo.

1. Apri l'app e accedi come l'utente che vuoi testare.
2. Chiama CapgoNotifications.register(...) dopo il login.
3. In Capgo, apri Notifiche > Ricerca destinatario.
4. Cerca usando lo stesso ID cliente esterno.

Dovresti vedere almeno un dispositivo attivo con:

• recipientKey
• deviceKey
• piattaforma android o ios
• stato dei permessi
• versione app
• versione plugin
• tag e attributi

Se la ricerca non restituisce alcun dispositivo, il percorso di invio non può colpire quell'utente.

Aggiungi listener di debug temporanei

Aggiungi listener temporanei durante i test. Rimuovi i log superflui prima del rilascio.

await CapgoNotifications.addListener('registrationChanged', (token) => {
  console.log('[CapgoNotifications] registrationChanged', token.value.slice(0, 12))
})

await CapgoNotifications.addListener('notificationReceived', (notification) => {
  console.log('[CapgoNotifications] notificationReceived', notification.id, notification.data)
})

await CapgoNotifications.addListener('notificationOpened', (event) => {
  console.log('[CapgoNotifications] notificationOpened', event.notification.id, event.actionId)
})

await CapgoNotifications.addListener('backgroundNotification', async (event) => {
  console.log('[CapgoNotifications] backgroundNotification', event.notification.id, event.notification.data)
  await event.finish()
})

Raccogli queste informazioni

Quando fai debugging con il tuo team o con il supporto Capgo, raccogli:

• L'app ID di Capgo.
• App package ID o iOS bundle ID.
• Piattaforma del dispositivo e versione OS.
• Versione dell'app e build number.
• Versione del plugin.
• ID del cliente esterno.
• recipientKey e deviceKey Dalla registrazione o dal lookup del destinatario.
• Campaign ID o notification ID.
• Se l'app era in foreground, background, force-closed o appena installata.
• I log del dispositivo relativi all'esecuzione che ha riprodotto il problema.

Usa i log del dispositivo

Mantieni un dispositivo fisico connesso mentre invii una notifica di test.

Su Android:

• Apri il Logcat di Android Studio.
• Filtra per ID pacchetto dell'app.
• Monitora la richiesta di permessi per le notifiche, il refresh del token nativo, la ricezione dei messaggi e i log del listener JavaScript.
• Se una notifica visibile non compare, controlla prima l'importanza del canale di notifica e lo stato dei permessi su Android 13+.

Su iOS:

• Esegui l'app da Xcode su un dispositivo fisico.
• Apri la console di Xcode o Dispositivi e simulatori log.
• Filtra per bundle ID e CapgoNotifications.
• Verifica AppDelegate.swift inoltra notifiche remote e che la capability background mode sia abilitata.

Invia prima un test in foreground, poi uno in background e infine uno silent update-check. Questo ordine permette di distinguere i problemi dei listener JavaScript dai limiti di consegna in background del sistema operativo.

Problemi di registrazione

Il setup di CLI non è terminato

Esegui il comando di setup dalla cartella che contiene capacitor.config.*:

npx @capgo/cli@latest notifications setup com.example.app

Se il comando non riesce a ricavare l'app ID, passalo esplicitamente come mostrato sopra. Se l'installazione del pacchetto fallisce, verifica che il nome del pacchetto sia @capgo/capacitor-notifications, verifica che il tuo registry npm sia https://registry.npmjs.org, controlla l'accesso alla rete, poi riesegui il comando.

Il dispositivo non compare nella ricerca destinatari

Controlla:

• register viene chiamato dopo che l'app ha un utente autenticato.
• externalId corrisponde all'ID utente che cerchi nella dashboard.
• identityProof è stato generato dal tuo backend per lo stesso appId e externalId.
• appId nella configure corrisponde all'app Capgo.
• consent non è impostato su false a meno che l'utente non abbia fatto opt-out.
• Il dispositivo ha accesso di rete a https://api.capgo.app.
• Il push token nativo è stato creato. Usa registrationChanged per confermare il refresh del token.

Identity Proof non valido

La prova è legata all'app ID Capgo e all'ID esterno. Se uno dei due valori cambia, generane una nuova.

Non mettere una prova in cache per sempre né riutilizzarla tra app diverse. Generalo dal tuo backend dopo il login, restituiscilo all'app e chiama register.

Dispositivo registrato ma permessi negati

Il plugin può registrare lo stato del dispositivo anche se l'utente ha negato il permesso. Il dispositivo resta comunque visibile, ma le notifiche visibili non verranno mostrate.

Usa una schermata di pre-autorizzazione prima del prompt del sistema operativo. Spiega cosa ottiene l'utente, poi chiedi il permesso solo quando l'azione ha senso.

Problemi di consegna

In coda ma non inviati

Controlla:

• Lo stato delle credenziali della piattaforma è configured in Capgo.
• L'ambiente worker contiene il riferimento esatto al secret mostrato nella dashboard.
• Il package ID o bundle ID dell'app corrisponde alla configurazione push della piattaforma.
• Il pubblico di destinazione corrisponde ad almeno un dispositivo attivo.
• La campagna non è limitata a un tag o segmento non presente sul dispositivo.

Inviate ma non ricevute

Controlla:

• Il dispositivo è online.
• L'app non è stata terminata forzatamente dall'utente.
• Il permesso di notifica dell'OS è concesso.
• Le restrizioni della batteria su Android non bloccano l'app durante i test.
• La Modalità Risparmio energia e le restrizioni sull'aggiornamento in background di iOS non influenzano la consegna in background.
• La notifica non è stata sostituita da un'altra con lo stesso collapse ID.

Le piattaforme push native possono accettare una notifica e poi ritardare, limitare, accorpare o scartare la consegna. Considera le statistiche di accettazione del provider come “accettate per la consegna”, non come prova che il dispositivo l'abbia visualizzata.

Ricevute ma non visualizzate

Controlla:

• L'app non era in primo piano. Le notifiche in foreground vengono solitamente inviate a JavaScript, così l'app può decidere quale UI mostrare.
• L'importanza del canale delle notifiche Android è sufficientemente alta da mostrare un avviso.
• Il permesso per le notifiche su Android 13+ è stato concesso.
• Le impostazioni di iOS Focus, il riepilogo notifiche o le impostazioni per singola app stanno nascondendo la notifica.
• La logica di rimozione dei badge o dell'app non sta eliminando le notifiche consegnate durante i test.

Problemi con le notifiche in background

Il callback in background non viene eseguito

Background notifications are best-effort. The OS can skip them.

Controlla:

• iOS ha Modalità in background > Notifiche remote abilitato.
• iOS AppDelegate.swift inoltra le notifiche remote a CapgoNotificationsRemoteNotification.
• Testa il comportamento in background su iOS usando un dispositivo fisico.
• L'app non è stata chiusa forzatamente dall'utente.
• Il background handler chiama finish().
• Il codice all'interno della callback è breve, sicuro per la rete e idempotente.

Su iOS, i push in background potrebbero subire un throttling se ne invii troppi, se impieghi troppo tempo o se l'utente apre raramente l'app. È il comportamento previsto della piattaforma.

Background avviato ma non terminato

Se le statistiche mostrano background_started senza background_finished, the JavaScript handler likely threw, timed out, or did not call finish().

Racchiudi l'handler in try/finally:

await CapgoNotifications.addListener('backgroundNotification', async (event) => {
  try {
    await doShortBackgroundWork(event.notification.data)
  } finally {
    await event.finish()
  }
})

Problemi con il controllo degli aggiornamenti silenziosi

Update Check Notification Arrives But No Update Installs

Controlla:

• @capgo/capacitor-updater è installato e configurato.
• autoUpdater è true o enableUpdaterIntegration è stata chiamata.
• Le impostazioni Notifiche dell'app consentono di controllare gli aggiornamenti push.
• Il dispositivo di destinazione appartiene al canale previsto.
• L'app ha un bundle più recente disponibile in Capgo.
• La modalità di installazione dell'update è corretta: next si accoda al prossimo riavvio o ciclo in background, set si installa non appena l'updater può farlo in sicurezza.

Esegui un controllo manuale mentre l'app è aperta:

const result = await CapgoNotifications.runUpdateCheck({
  enabled: true,
  installMode: 'next',
})

console.log(result)

Se il controllo manuale restituisce unavailable, controlla prima la configurazione del plugin updater.

Problemi con i Badge

Controlla:

• Il target punta al dispositivo corretto durante la ricerca del destinatario.
• La piattaforma supporta i badge dell'app per il launcher o la home screen in test.
• L'utente non ha disabilitato i badge nelle impostazioni notifiche del sistema operativo.
• L'app non pulisce i badge immediatamente all'avvio.
• Non stai eseguendo in locale setBadge e l'invio dei badge al backend.

Problemi con le Statistiche

Le statistiche sembrano duplicate

L'invio delle notifiche segue la logica at-least-once. Il retry della coda e quello della piattaforma possono duplicare un invio. Usa gli ID delle notifiche e i collapse ID quando l'azione della tua app deve essere idempotente.

Mancano statistiche per i dispositivi vecchi

Il registro dell'Analytics Engine è per i dispositivi attivi, non un database permanente. Il plugin dovrebbe aggiornare la registrazione all'avvio dell'app, al refresh del token, al cambio di ID esterno e periodicamente prima della scadenza della retention dei dispositivi attivi.

Mancano gli eventi di apertura (Open Events)

Controlla:

• The notification includes a stable id.
• notificationOpened un listener è registrato durante l'avvio dell'app.
• L'app non sta sostituendo il flusso nativo di apertura con un custom code prima che il plugin lo rilevi.
• L'utente ha effettivamente toccato la notifica invece di aprire l'app manualmente.

Comandi di debug di API

Cerca un destinatario:

curl -X POST 'https://api.capgo.app/notifications/recipients/lookup' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: CAPGO_API_KEY' \
  -d '{
    "appId": "com.example.app",
    "externalId": "customer-user-123"
  }'

Read stats:

curl 'https://api.capgo.app/notifications/stats?app_id=com.example.app&days=7' \
  -H 'x-api-key: CAPGO_API_KEY'

Invia un test in foreground:

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": "Capgo test",
      "body": "Open this notification to test events.",
      "data": { "debug": "true" }
    }
  }'

Cause profonde più comuni

Sintomo	Causa probabile
Dispositivo non trovato nel lookup	register non chiamata, mismatch della prova, consenso falso, app ID errato.
Permesso negato	Prompt dell'OS negato o non ancora richiesto.
In coda ma senza statistiche di invio	Le credenziali della piattaforma mancano o sono disabilitate.
Inviata ma senza statistiche di ricezione	Dispositivo offline, throttling dell'OS, app forzata o token non valido.
Log notifica in foreground ma nessun banner	L'app è in primo piano e deve mostrare la propria UI in-app.
In background non viene mai eseguito su iOS	Capabilities mancanti, AppDelegate senza forwarding, app chiusa forzatamente o throttling dell'OS.
Il controllo dell'update non produce effetti	Integrazione updater disabilitata, nessun bundle più recente, canale errato o modalità di installazione errata.
I badge vengono resettati	L'avvio dell'app code cancella i badge o causa race condition tra scritture locali e backend.

Continua da Debugging

Dopo la registrazione del dispositivo e un test riuscito, usa Per iniziare per integrare badge, targeting delle campagne e silent update check nella tua app in produzione.