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 può vedere il dispositivo.

1. Apre l'app e si iscrive come l'utente che vuoi testare.
2. Chiamare CapgoNotifications.register(...) contesto: frammento di testo HTML da una stringa Capgo UI più lunga (chiave madre `appflow_migration_step2`). Pagina/area: Appflow comparison / migrazione marketing copy. Ruolo: frase di copertina del sito web. Visto in: pagina ionic-appflow.astro. Preservare i termini di prodotto/marca e sviluppatore esattamente. Chiave di messaggio `appflow_migration_step2` (Appflow Migration Step2).
3. In Capgo, apri Notifiche > Ricerca del destinatario.
4. Cerca con lo stesso ID di cliente esterno.

Devi vedere almeno un dispositivo attivo con:

• recipientKey
• deviceKey
• piattaforma android o ios
• La piattaforma o il plugin che si utilizza.
• stato di autorizzazione
• versione dell'app
• versione del plugin

etichette e attributi

Se la ricerca non restituisce alcun dispositivo, il percorso di invio non può raggiungere quel utente.

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

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 costruzione dell'applicazione.
• Versione del plugin.
• ID del cliente esterno.
• recipientKey E e deviceKey o registrazione o ricerca destinatario.
• ID della campagna o ID della notifica.
• Se l'app era in primo piano, in background, chiusa forzatamente o appena installata.
• Log del dispositivo dal run che ha riprodotto il problema.

Usa Log del dispositivo

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

Sul sistema Android:

• Apre Logcat di Android Studio.
• Filtrare per l'ID del pacchetto dell'app.
• Osserva le registrazioni della richiesta di autorizzazione per le notifiche, del rinnovo del token nativo, delle ricezioni di messaggi e dei log dei listener JavaScript.
• If a visible notification does not show, inspect the notification channel importance and Android 13+ permission state first.

On iOS:

• Esegui l'applicazione da Xcode su un dispositivo fisico.
• Apre il console di Xcode o Dispositivi e Simulatori Filtra per l'ID del pacchetto e
• Conferma CapgoNotifications.
• che le notifiche remote vengano inviate e che la capacità di background sia abilitata. AppDelegate.swift Inviare un test di foreground, poi un test di background, poi un test di aggiornamento silenzioso. Questo ordine separa le questioni relative ai listener JavaScript da i limiti di consegna del sistema operativo per il background.

Problemi di registrazione

Sottosezione intitolata “Problemi di registrazione”

CLI Setup Non Eseguito

Eseguire il comando di setup 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 app, passalo esplicitamente come mostrato sopra. Se l'installazione del pacchetto fallisce, conferma che Capgo abbia abilitato l'accesso ai pacchetti in anteprima privata per il tuo npm account, quindi ripeti 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 e externalId.
• appId in configure corrisponde all'applicazione 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.

Prova di Identità non valida

La prova è legata all'ID dell'applicazione 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 chiamala register.

Dispositivo Registrato Ma Concesso Denegato

Il plugin può registrare lo stato del dispositivo anche quando l'utente ha negato il permesso. È possibile visualizzare il dispositivo, ma le notifiche visibili non verranno visualizzate.

Usa una schermata di introduzione dei permessi prima della richiesta del sistema operativo. Spiega cosa l'utente ottiene, poi chiedi il permesso 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.
• Il pacchetto ID o bundle ID nell'app corrisponde alla configurazione di push 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.

Inviato ma Non Ricevuto

Controlla:

• Il dispositivo è online.
• L'app non è stata fermata forzatamente dall'utente.
• La permessione di notifica del sistema operativo è 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 nativi possono accettare una notifica e ritardare, limitare, coalescere o eliminare la consegna in un secondo momento. Trattare le statistiche accettate dal provider come “accettate 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 consegnate al JavaScript affinché l'app possa decidere quale interfaccia da mostrare.
• L'importanza del canale di notifica Android è abbastanza alta da visualizzare un avviso.
• Il permesso di notifica Android 13+ è stato concesso.
• Il focus, la sintesi delle notifiche o le impostazioni delle notifiche per app non stanno nascondendo la notifica.
• La logica di pulizia della badge o l'apertura dell'app non stanno eliminando le notifiche consegnate durante le prove.

Sottosezione intitolata “Problemi di notifica in background”

Sottosezione intitolata “Problemi di notifica in background”

Gli avvisi di background sono di tipo best-effort. L'OS può saltarli.

Controlla:

• L'iOS ha Modalità di background > Avvisi remoti abilitato.
• L'iOS AppDelegate.swift invia gli avvisi remoti 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 della callback in modo breve, sicuro per la rete e idempotente.

Su iOS, i push in background potrebbero essere rallentati se invii troppi, utilizzate troppo tempo o l'utente apre raramente l'app. Questo è il comportamento previsto della piattaforma.

Avviato in Background Ma Non Completato

Se i dati mostrano background_started senza background_finishedil gestore JavaScript ha probabilmente 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 Silenzioso dell'Aggiornamento

La Notifica di Controllo dell'Aggiornamento Arriva Ma Nessun Aggiornamento Si Installa

Controlla:

• @capgo/capacitor-updater è installato e configurato.
• autoUpdater è true o enableUpdaterIntegration o
• è stato chiamato.
• Il menu delle impostazioni delle notifiche dell'app consente di effettuare controlli di aggiornamento push.
• The app has a newer bundle available in Capgo.
• L'app ha una versione più recente disponibile in __CAPGO_KEEP_0__. next La tua modalità di installazione dell'aggiornamento è corretta: set si attiva in coda per la prossima riavvio o ciclo di background

si installa non appena l'aggiornatore può farlo in sicurezza.

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

console.log(result)

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

Problemi di Badge

Controlla:

• La destinazione si risolve sul dispositivo giusto nella ricerca di destinatari.
• La piattaforma supporta le badge per l'applicazione per il lanciatore o la schermata iniziale che si sta testando.
• L'utente non ha disabilitato le badge nei impostazioni di notifica del sistema operativo.
• L'applicazione non cancella le badge immediatamente all'avvio.
• Non stai eseguendo chiamate locali setBadge contro invii di badge backend.

Problemi di Statistiche

Illochi Statistiche

Il plugin di notifica invia almeno una volta. La coda di riprova e la riprova della piattaforma possono duplicare una spedizione. Utilizzare gli ID delle notifiche e gli ID di collasso quando l'azione dell'applicazione deve essere idempotente.

Le statistiche mancano per dispositivi vecchi

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

Gli eventi aperti mancano

Controlla:

• Il notifica include un identificatore stabile id.
• notificationOpened l'ascoltatore è registrato durante l'avvio dell'applicazione.
• La applicazione 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'applicazione 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 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" }
    }
  }'

Cause comuni

Sintomo	Causa probabile
Dispositivo mancante nella ricerca	register non chiamato, prova non corrispondente, consenso falso, ID app non corrispondente.
Permesso negato	Richiesta di avvio del sistema operativo negata o non richiesta ancora.
In coda ma senza statistiche inviate	I credenziali del sistema operativo sono mancanti o disabilitate.
Invio ma nessuna statistica ricevuta	Dispositivo offline, rallentamento del sistema operativo, app chiusa forzatamente o token non valido.
Registri delle notifiche in primo piano ma nessuna banner	L'applicazione è in primo piano e deve visualizzare la propria interfaccia utente in-app.
Background non esegue mai su iOS	Capacità mancanti, AppDelegate di forwarding mancante, app chiusa forzatamente o rallentamento del sistema operativo.
Controllo dell'aggiornamento non fa nulla	L'integrazione dell'aggiornamento disabilitata, nessuna versione più recente disponibile, canale sbagliato o modalità di installazione mal compresa.
Badge resettati	L'avvio dell'applicazione code cancella le badge o le scritte locali e backend delle badge si contendono.

Continua da Debugging

Una volta che il dispositivo si registra e un avviso di test funziona, utilizza Iniziare per collegare le badge, la campagna di targeting e le verifiche di aggiornamento silenzioso nella tua app di produzione.