Debugging

Usa questo elenco di controllo quando una notifica non si registra, non arriva, non si mostra o non aggiorna Capgo statistiche.

Inizia con il registro del dispositivo

Prima di debuggare il code nativo, conferma che Capgo possa vedere il dispositivo.

1. Apre l'app e si iscrive come l'utente che vuole testare.
2. Chiama CapgoNotifications.register(...) dopo l'iscrizione.
3. In Capgo, apri Notifiche > Ricerca del destinatario.
4. Cerca con lo stesso ID del cliente esterno.

Devi vedere almeno un dispositivo attivo con:

• recipientKey
• deviceKey
• piattaforma android o ios
• stato di autorizzazione
• versione dell'app
• versione del plugin
• etichette e attributi

Se la ricerca non restituisce alcun dispositivo, la send path non può targetare quel utente.

Aggiungi Ascoltatori di Debug Temporanei

Aggiungi ascoltatori temporanei durante le prove. Elimina i log rumorosi prima di distribuire.

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 si debugga con il proprio team o Capgo supporto, raccogli:

• Capgo ID dell'applicazione.
• ID del pacchetto dell'applicazione o ID del bundle iOS.
• Piattaforma e versione del sistema operativo del dispositivo.
• Versione e numero di build dell'applicazione.
• Versione del plugin.
• ID del cliente esterno.
• recipientKey e deviceKey da registrazione o ricerca del destinatario.
• ID della campagna o ID della notifica.
• Sia che l'applicazione fosse in primo piano, in background, chiusa forzatamente o appena installata.
• I log del dispositivo dal run che ha riprodotto il problema.

Usa i Log del Dispositivo

Tieni collegato un dispositivo reale mentre invii una notifica di test.

Su Android:

• Apri Logcat di Android Studio.
• Filtra per l'ID del pacchetto dell'applicazione.
• Cerca i log della richiesta di autorizzazione per le notifiche, del rinnovo del token nativo, della ricezione dei messaggi e dei listener JavaScript.
• Se una notifica visibile non si mostra, controlla prima l'importanza del canale delle notifiche e lo stato delle autorizzazioni di Android 13+.

Su iOS:

• Esegui l'app da Xcode su un dispositivo fisico.
• Apri la console di Xcode o Dispositivi e Simulatori i log.
• Filtra per ID bundle e CapgoNotifications.
• Conferma AppDelegate.swift permette le notifiche remote e che la capacità di modalità di background sia abilitata.

Inviare un test di foreground, poi un test di background, poi un test di aggiornamento silenzioso. Questo ordine separa le questioni dei listener JavaScript da i limiti di consegna di background del sistema operativo.

Problemi di registrazione

CLI Setup Non È Terminato

Esegui il comando di configurazione dal folder che contiene capacitor.config.*:

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

Se il comando non riesce a inferire il tuo ID dell'applicazione, passalo esplicitamente come mostrato sopra. Se l'installazione del pacchetto fallisce, conferma che Capgo abbia abilitato l'accesso ai pacchetti di anteprima privata per il tuo npm account, quindi esegui nuovamente il comando.

Il dispositivo non appare nella ricerca del destinatario

Controlla:

• register viene chiamato dopo che la tua app ha un utente autenticato.
• externalId corrisponde all'ID dell'utente che cerchi nel dashboard.
• identityProof è stato creato dal tuo backend per lo stesso appId e externalId.
• appId in configure corrisponde all'app Capgo.
• consent non è impostato false a meno che l'utente non abbia optato fuori da.
• Il dispositivo ha accesso a rete a https://api.capgo.app.
• Il token di push nativo è stato creato. Utilizza registrationChanged per confermare il rinnovo del token.

Prova di Identità Non Validato

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

Non memorizzare una prova per sempre o reimpiegare una prova tra le app. Crea una nuova prova dal tuo backend dopo l'accesso, restituiscila all'app e chiama register.

Registrato dispositivo ma con permesso negato

Il plugin può registrare lo stato del dispositivo anche quando l'utente ha negato il permesso. Puoi ancora vedere il dispositivo, ma le notifiche visibili non appariranno.

Usa una schermata di autorizzazione prima della richiesta del sistema operativo. Spiega cosa il utente riceve, poi chiedi l'autorizzazione solo quando l'azione ha senso.

Problemi di consegna

In coda ma non inviato

Controlla:

• Lo stato dei credenziali della piattaforma è configured in Capgo.
• L'ambiente del worker contiene la chiave segreta esatta mostrata dalla dashboard.
• L'ID del pacchetto o l'ID del bundle nell'app corrisponde alla configurazione di invio della piattaforma.
• L'audience di destinazione si risolve in almeno un dispositivo attivo.
• La campagna non è limitata a un tag o segmento che il dispositivo non possiede.

Ricevuto ma non ricevuto

Verifica:

• Il dispositivo è online.
• L'app non è stata fermata dall'utente.
• La richiesta di notifica del sistema operativo è stata concessa.
• Le restrizioni della batteria di Android non stanno bloccando l'app durante le prove.
• Le restrizioni di iOS Low Power Mode e background refresh non stanno influenzando la consegna in background.
• La notifica non è stata sostituita da un'altra notifica con lo stesso ID di collasso.

Le piattaforme di push nativo possono accettare una notifica e ritardare, rallentare, coalescere o eliminare la consegna in un secondo momento. Trattare le statistiche di accettazione del provider come “accettato per la consegna”, non come prova che il dispositivo l'abbia visualizzata.

Ricevuto ma non visualizzato

Controlla:

• L'app non era in primo piano. Le notifiche in primo piano sono solitamente inviate al JavaScript affinché l'app possa decidere quale interfaccia utente mostrare.
• L'importanza del canale di notifica Android è abbastanza alta da visualizzare un avviso.
• La richiesta di autorizzazione di notifica Android 13+ è stata concessa.
• Le impostazioni di notifica iOS Focus, di riassunto delle notifiche o per-app non stanno nascondendo la notifica.
• La logica di pulizia della badge o di apertura dell'app non sta eliminando le notifiche consegnate durante le prove.

Problemi di Notifiche in Background

La callback in background non viene eseguita.

Le notifiche in background sono di tipo best-effort. L'System può saltarle.

Controlla:

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

Su iOS, i push di background possono essere rallentati se invii troppi, utilizzo troppo tempo o l'utente apre raramente l'app. Questo è il comportamento di piattaforma previsto.

Avviato in background ma non completato

Se i dati statistici mostrano background_started senza background_finished, il gestore JavaScript ha probabilmente lanciato un errore, è scaduto o non ha chiamato finish().

Avvolgere il gestore in try/finally:

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

Problemi di controllo di aggiornamento silenzioso

La notifica di controllo di aggiornamento arriva ma nessun aggiornamento viene installato

Verifica:

• @capgo/capacitor-updater è installato e configurato.
• autoUpdater è true o enableUpdaterIntegration era chiamato.
• Le impostazioni delle notifiche dell'app consentono di verificare gli aggiornamenti push.
• Il dispositivo di destinazione appartiene al canale che si aspetta.
• L'app ha una versione più recente del pacchetto disponibile in Capgo.
• Il tuo modo di installazione dell'aggiornamento è corretto: next si mette in coda per il prossimo riavvio o ciclo di background, set si installa non appena l'aggiornatore 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 dell'aggiornatore.

Problemi del Badge

Verifica:

• Il target si risolve sul dispositivo giusto nella ricerca del destinatario.
• La piattaforma supporta i badge per l'applicazione per il launcher o la schermata iniziale in corso di test.
• L'utente non ha disabilitato i badge nelle impostazioni di notifica del sistema operativo.
• L'applicazione non cancella i badge immediatamente all'avvio.
• Non stai eseguendo chiamate locali sulle invio dei badge backend. setBadge Problemi delle Statistiche

Sezione intitolata “Problemi delle Statistiche”

Statistiche duplicate

La notifica di invio è almeno una volta. La coda di riprova e la riprova della piattaforma possono duplicare un invio. Utilizzare gli ID delle notifiche e gli ID di collasso quando l'azione dell'app deve essere idempotente.

Manca i dati statistici per i dispositivi vecchi

L'elenco dei registri dell'engine di analisi è per dispositivi attivi, non un database per sempre. Il plugin dovrebbe aggiornare la registrazione all'avvio dell'app, al rinnovo del token, al cambio dell'ID esterno e periodicamente prima della finestra di conservazione dei dispositivi attivi.

Manca gli eventi aperti

Controlla:

• La notifica include un indirizzo stabile id.
• notificationOpened Si è registrato un ascoltatore durante l'avvio dell'app.
• L'app non sostituisce il flusso di apertura nativo con un custom code prima che il plugin lo veda.
• L'utente ha effettivamente premuto la notifica piuttosto che aprire l'app manualmente.

Comandi di debug 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"
  }'

Leggi le statistiche:

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 primo piano:

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" }
    }
  }'

Causali di base comuni

Sintomo	Causa probabile
Dispositivo mancante dalla ricerca	register non chiamato, prova non corrispondente, consenso falso, ID app non corrispondente.
Denegato il permesso	Richiesta di avvio del sistema operativo negata o non richiesta ancora.
In coda ma senza statistiche inviate	Manca o è disabilitato il credenziale del sistema.
Inviate ma senza statistiche ricevute	Dispositivo offline, rallentamento del sistema operativo, app forzatamente fermata o token non valido.
Log delle notifiche in primo piano ma senza banner	L'applicazione è in primo piano e deve visualizzare la propria interfaccia utente in-app.
Il background non viene mai eseguito su iOS	Manca una capacità, manca la delega di AppDelegate, l'applicazione viene chiusa forzatamente o il sistema di throttling.
La verifica dell'aggiornamento non fa nulla	L'integrazione dell'aggiornamento è disabilitata, non ci sono bundle più recenti, canale sbagliato o modalità di installazione mal interpretata.
Il badge viene resettato	L'avvio dell'applicazione code cancella i badge o le scritture locali e backend dei badge si verificano in una corsa.

Continua da Debugging

Dopo che il dispositivo si è registrato e una notifica di prova funziona, utilizza Iniziare per collegare i badge, la targeting delle campagne e i controlli di aggiornamento silenzioso nella tua applicazione di produzione.