Debugging

Usa questo elenco di controlli 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 dispositivo nativo code, assicurati che Capgo possa visualizzare il dispositivo.

1. Apri l'app e accedi con l'utente che desideri testare.
2. Chiamata CapgoNotifications.register(...) dopo l'accesso.
3. In Capgo, apri Notifiche > Ricerca destinatario.
4. Cerca con lo stesso ID del cliente esterno.

Vorresti 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 il lookup non restituisce alcun dispositivo, il percorso di invio non può mirare a 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 questa informazione

Esegui il debug con il tuo 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.
• Se l'applicazione era in primo piano, in background, chiusa forzatamente o appena installata.
• Log del dispositivo dal run che ha riprodotto il problema.

Usa i Log dei Dispositivi

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

Su Android:

• Apre Logcat di Android Studio.
• Filtra per l'ID del pacchetto dell'app.
• Controlla le richieste di autorizzazione, il rinnovo dei token nativi, l'arrivo dei messaggi e i log dei listener JavaScript.
• Se una notifica visibile non si mostra, controlla prima l'importanza del canale di notifica e lo stato di autorizzazione di Android 13+.

Su iOS:

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

Invia un test di foreground, poi un test di background, poi un test di aggiornamento silenzioso. Questo ordine separa le problematiche dei listener JavaScript dalle limitazioni di consegna del background del sistema operativo.

Problemi di registrazione

CLI Setup Non È Terminato

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

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

If il comando non riesce a inferire il tuo ID app, passalo esplicitamente come mostrato sopra. Se l'installazione del pacchetto fallisce, conferma il nome del pacchetto è @capgo/capacitor-notificationsverifica che il tuo registro npm sia https://registry.npmjs.orgcontrolla l'accesso alla rete, quindi esegui nuovamente il comando.

Dispositivo Non Compare Nella Ricerca Destinatario

Controlla:

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

Identità non valida

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 riutilizzare una prova tra app. Crea una nuova prova dal tuo backend dopo l'accesso, restituiscila all'app e chiama register.

Dispositivo Registrato 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 uno schermo di autorizzazione di base prima della richiesta del sistema operativo. Spiega cosa il utente riceve, quindi 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 riferimento segreto esatto mostrato 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.

Invio ma non ricevuto

Controlla:

• Il dispositivo è online.
• L'app non è stata fermata dall'utente.
• L'autorizzazione all'avviso del sistema operativo è concessa.
• Le restrizioni della batteria di Android non stanno bloccando l'app durante le prove.
• iOS Modo basso consumo e restrizioni di aggiornamento in background non influenzano la consegna in background.
• L'avviso non è stato sostituito da un altro avviso con lo stesso ID di collasso.

Il provider di push nativi può accettare un avviso e ritardare, rallentare, coalescere o eliminarne la consegna in un secondo momento. Tratta i dati di accettazione del provider come “accettato per la consegna”, non come prova che il dispositivo l'abbia visualizzato.

Ricevuto ma non visualizzato

Controlla:

• L'app non era in primo piano. Le notifiche in primo piano sono generalmente 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.
• Il permesso di notifica Android 13+ è stato concesso.
• Impostazioni di notifica iOS, riassunto delle notifiche o impostazioni di notifica per app non nascondono la notifica.
• La logica di rimozione delle notifiche non sta cancellando quelle già inviate durante le prove.

Problemi con le Notifiche in Background

La Callback in Background Non Si Esegue

Le notifiche in background sono a prestazioni ottimali. L'SO 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 in rete e idempotente.

Sui dispositivi iOS, le push di background possono essere rallentate se invii troppi, utilizzo troppo tempo o l'utente apre raramente l'app. Questo è il comportamento previsto della piattaforma.

Il background è stato avviato ma non completato

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

Avvolgi 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

Notifica di Controllo Aggiornamento Arriva Ma Nessun Aggiornamento Installa

Controlla:

• @capgo/capacitor-updater è installato e configurato.
• autoUpdater è true o enableUpdaterIntegration era chiamato.
• Le impostazioni delle notifiche dell'app consentono i controlli di aggiornamento push.
• La dispositivo di destinazione appartiene al canale che si aspetta.
• L'app ha un pacchetto più recente disponibile in Capgo.
• Your update install mode is correct: next si attiva per la prossima 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, inspect the updater plugin setup first.

Problemi di Badge

Controlla:

• La destinazione risolve il dispositivo destro nella ricerca del destinatario.
• La piattaforma supporta le barrette dell'applicazione per il lanciatore o la schermata iniziale che viene testata.
• L'utente non ha disabilitato le barrette nelle impostazioni di notifica del sistema.
• L'applicazione non cancella le barrette immediatamente all'avvio.
• Non stai eseguendo chiamate locali setBadge contro invii di badge backend.

Problemi di Statistiche

I dati statistici sembrano duplicati

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.

Stats Manca Per Dispositivi Vecchi

L'elenco dei registri dell'Engine di Analytics è 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.

Eventi Aperti Manca

Controlla:

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

API Comandi di debug

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

Cause comuni di errore

Sintomo	Causa probabile
Dispositivo mancante dal lookup	register non chiamato, prova non corrispondente, consenso falso, ID app non corrispondente.
Permesso negato	Richiesta di OS non autorizzata o non richiesta ancora.
In coda ma senza statistiche inviate	Manca o è disabilitato il credenziale del sistema.
Inviate ma senza statistiche ricevute	Device offline, OS throttling, app force-stopped, or token invalid.
Log delle notifiche in primo piano ma nessun banner	L'app è in primo piano e deve mostrare la propria interfaccia utente.
Il background non esegue mai su iOS	Capacità mancanti, mancata elaborazione di AppDelegate, forzatura dell'applicazione, o rallentamento del sistema operativo.
La verifica dell'aggiornamento non fa nulla	L'integrazione dell'aggiornatore disabilitata, nessun bundle più recente, canale o modalità di installazione errato.
Il badge viene resettato	Avvio dell'app code cancella i badge o elimina la concorrenza tra scritture locali e backend.

Continua da Debugging

Dopo che il dispositivo si è registrato e una notifica di test funziona, utilizza Getting Started cable badge, targeting della campagna e controlli di aggiornamento silenzioso nella tua app di produzione.