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 connette come l'utente che vuoi testare.
2. Chiamare CapgoNotifications.register(...) contexto: 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. Visualizzato in: pagina ionic-appflow.astro. Preserva i termini del prodotto/marca e del developer esattamente. Chiave del messaggio `appflow_migration_step2` (Appflow Migration Step2).
3. In Capgo, apri Notifications > 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
• La piattaforma o l'applicazione
• 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ò essere indirizzato a 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 build 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:

• Apri Logcat di Android Studio.
• Filtra 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 un notifica visibile non si visualizza, controlla l'importanza del canale di notifica e lo stato di autorizzazione di Android 13+ prima.

On iOS:

• Esegui l'applicazione da Xcode su un dispositivo fisico.
• Apre la console di Xcode o Dispositivi e simulatori Filtra per l'ID del bundle e
• Conferma CapgoNotifications.
• che le notifiche remote vengono inviate e che la capacità di background è abilitata. AppDelegate.swift Inviare un test di foreground per primo, poi un test di background, poi un test di aggiornamento silenzioso. Questo ordine separa le problematiche dei listener JavaScript dalle limitazioni di consegna di background del sistema.

Problemi di registrazione

Problemi di registrazione

CLI Setup Did Not Finish

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 private-preview per il tuo npm account, quindi riprova il comando.

Il dispositivo non appare nella ricerca di destinatari

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 Di Rifiutare

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.

Utilizza una schermata di introduzione dei permessi prima della richiesta del sistema operativo. Spiega cosa l'utente riceverà, poi chiedi il permesso solo quando l'azione ha senso.

Problemi di consegna

Non Spedito

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 di 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, rallentare, 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.

Ricevuta ma non visualizzata

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 è sufficiente per visualizzare un avviso.
• La richiesta di autorizzazione di notifica di Android 13+ è stata concessa.
• Il riassunto delle notifiche, la modalità di notifica Focus 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 inoltra gli avvisi remoti a CapgoNotificationsRemoteNotification.
• Per testare il comportamento di background dell'iOS su un dispositivo fisico.
• L'app non è stata chiusa dall'utente.
• Il gestore di background chiama finish().
• Lavora all'interno della callback per brevi periodi, in modo sicuro per la rete e idempotente.

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

Avvio in background ma non completato

Se i dati mostrano background_started senza background_finished, il gestore JavaScript probabilmente ha 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 silenzioso dell'aggiornamento

L'arrivo della notifica di controllo dell'aggiornamento ma nessun aggiornamento viene installato

Controlla:

• @capgo/capacitor-updater è installato e configurato.
• autoUpdater o true o enableUpdaterIntegration o
• o
• è stato chiamato.
• The app has a newer bundle available in Capgo.
• Il dispositivo di destinazione appartiene al canale che si aspetta. next L'app ha una versione più recente disponibile in __CAPGO_KEEP_0__. set La tua modalità di installazione di aggiornamento è corretta:

si attiva in coda per il prossimo riavvio o ciclo di background,

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 risolve il dispositivo giusto nella ricerca di destinatari.
• La piattaforma supporta le badge per l'applicazione per il launcher o la schermata iniziale che viene testata.
• L'utente non ha disabilitato le badge nei impostazioni di notifiche del sistema.
• L'app non cancella le badge immediatamente al avvio.
• Non stai eseguendo chiamate locali setBadge contro invii di badge backend.

Problemi di Statistiche

Aspetto Duplicato delle Statistiche

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.

Le Statistiche Mancano per i 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:

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

Casi di causa comuni

Sintomo	Causa probabile
Dispositivo mancante dalla ricerca	register non chiamato, incongruenza di prova, 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 piattaforma sono mancanti o disabilitate.
Invio ma nessuna statistica ricevuta	Dispositivo offline, rallentamento del sistema operativo, app forzatamente fermata o token non valido.
Log delle notifiche in primo piano ma nessuna banner	L'applicazione è in primo piano e deve visualizzare la propria interfaccia utente in-app.
Il background non esegue mai su iOS	Manca una capacità, manca la delega di AppDelegate, l'app è stata forzatamente fermata o rallentamento del sistema operativo.
La verifica dell'aggiornamento non fa nulla	L'integrazione dell'aggiornamento disabilitata, nessuna versione più recente disponibile, canale sbagliato o modalità di installazione mal compresa.
La badge viene resettata	L'avvio dell'app code cancella le badge o le scritte locali e backend delle badge si contendono.

Continua da Debugging

Una volta che il dispositivo si è registrato e una notifica di prova funziona, utilizza Iniziare per collegare le badge, la campagna di targeting e le verifiche di aggiornamento silenzioso nella tua app di produzione.