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. Visibile in: pagina ionic-appflow.astro. Preserva i termini di prodotto/marca e i termini di sviluppatore 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 il plugin che si desidera utilizzare.
• 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 costruzione dell'applicazione.
• Versione del plugin.
• ID del cliente esterno.
• recipientKey And deviceKey Ecco le informazioni
• ID della campagna o ID della notifica
• Stato dell'applicazione (in primo piano, in background, chiusa forzatamente o appena installata)
• Log del dispositivo dal run che ha riprodotto il problema

Usa i Log del Dispositivo

Assicurati di avere sempre un dispositivo reale collegato mentre invii una notifica di test.

Esegui le seguenti operazioni su Android:

• Apri Logcat di Android Studio.
• Filtrare per l'ID del pacchetto dell'applicazione.
• Controlla le registrazioni relative alla richiesta di autorizzazione per le notifiche, al rinnovo del token nativo, alle ricezioni di messaggi e ai log dei listener JavaScript.
• Se una 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 pacchetto 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 operativo.

Problemi di registrazione

Sezione intitolata “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 dell'applicazione, passalo esplicitamente come mostrato sopra. Se l'installazione del pacchetto fallisce, conferma il nome del pacchetto è @capgo/capacitor-notificationsverifica il tuo registro npm https://registry.npmjs.orgverifica l'accesso alla rete, quindi riprova il comando.

Il dispositivo non appare nella ricerca di destinatari

Controlla:

• register è chiamato dopo che il tuo app ha un utente autenticato.
• externalId corrisponde all'ID utente che stai cercando nella dashboard.
• identityProof è stato creato dal tuo backend per lo stesso appId e externalId.
• appId in configure corrisponde all'app Capgo.
• consent non è impostato su false a meno che l'utente non abbia optato fuori.
• 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 valido

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

Dispositivo Registrato Ma Concesso Il 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.

Utilizza 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

Problemi di consegna in coda

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 push del piattaforma.
• L'audience di destinazione si risolve in almeno un dispositivo attivo.
• La campagna non è limitata a una 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 il testing.
• iOS Modo basso consumo di energia e restrizioni di refresh in background non stanno influenzando la consegna in background.
• La notifica non è stata sostituita da un'altra notifica con lo stesso ID di crollo.

Le piattaforme di push nativo possono accettare una notifica e ritardare, limitare, 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 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.
• La permessione di notifica Android 13+ è stata concessa.
• Le impostazioni di Focus, sommario di notifica o impostazioni di notifica per app di iOS non stanno nascondendo la notifica.
• La logica di pulizia della badge o di apertura dell'app non sta eliminando le notifiche consegnate durante il testing.

Problemi di notifiche in background

La callback in background non viene eseguita

Le notifiche in background sono a prestazioni ottimali. L'OS può saltarle.

Controlla:

• L'iOS ha Modalità in background > Notifiche remote abilitate.
• L'iOS AppDelegate.swift invia le notifiche remote a CapgoNotificationsRemoteNotification.
• Per testare il comportamento in background dell'iOS, utilizza un dispositivo fisico.
• La app non è stata chiusa forzatamente dall'utente.
• Il gestore di background chiama finish().
• Lavorare all'interno del callback è breve, sicuro della rete e idempotente.

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

Inizio di Background Ma Non Finito

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 di Aggiornamento Silenzioso

Verifica dell'aggiornamento: la notifica arriva ma non si installa l'aggiornamento

Controlla:

• @capgo/capacitor-updater è installato e configurato.
• autoUpdater è true o enableUpdaterIntegration contexto: frammento di testo HTML da una stringa di Capgo UI più lunga (chiave genitoriale `alternatives_cta_questions`). Pagina/area: pagina di confronto delle alternative di Capacitor per l'aggiornamento in tempo reale. Ruolo: lungo paragrafo di marketing o legale. Visto in: pagina alternatives.astro. Preservare esattamente i termini di prodotto e marchio di Capgo e i termini di sviluppatore. Chiave del messaggio `alternatives_cta_questions` (Domande di azione per le alternative). | Frammento di testo HTML da una stringa di Capgo UI più lunga (chiave genitoriale `appflow_cta_questions`). Pagina/area: pagina di confronto e migrazione di Appflow per la copia di marketing. Ruolo: lungo paragrafo di marketing o legale. Visto in: pagina ionic-appflow.astro. Preservare esattamente i termini di prodotto e marchio di Capgo e i termini di sviluppatore. Chiave del messaggio `appflow_cta_questions` (Domande di azione per Appflow). | Frammento di testo HTML da una stringa di Capgo UI più lunga (chiave genitoriale `capwesome_cta_questions`). Pagina/area: pagina di confronto di Capawesome. Ruolo: lungo paragrafo di marketing o legale. Visto in: pagina capwesome.astro. Preservare esattamente i termini di prodotto e marchio di Capgo e i termini di sviluppatore. Chiave del messaggio `capwesome_cta_questions` (Domande di azione per Capwesome). | Frammento di testo HTML da una stringa di Capgo UI più lunga (chiave genitoriale `consulting_faq_subtitle`). Pagina/area: pagina dei servizi di consulenza. Ruolo: sottotitolo o didascalia della sezione. Visto in: pagina consulting.astro. Preservare esattamente i termini di prodotto e marchio di Capgo e i termini di sviluppatore. Chiave del messaggio `consulting_faq_subtitle` (Sottotitolo delle domande frequenti per la consulenza). | Pagina/area: pagina di confronto e migrazione di Appflow per la copia di marketing. Ruolo: breve etichetta di UI o elemento di navigazione. Visto in: pagina ionic-appflow.astro, pagina ionic-enterprise-plugins.astro, pagina soluzioni/ionic-enterprise-plugins.astro. Chiave del messaggio `appflow_plugins_or` (Appflow Plugins o).
• è stato chiamato.
• L'impostazione delle notifiche dell'app consente le verifiche di aggiornamento in push.
• The app has a newer bundle available in Capgo.
• L'app ha un bundle più recente disponibile in __CAPGO_KEEP_0__. next Il tuo modo di installazione dell'aggiornamento è corretto: set 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 di Badge

Controlla:

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

Problemi di Statistiche

Le statistiche sembrano duplicate

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

Le statistiche mancano per dispositivi vecchi

L'engine di Analytics è per dispositivi attivi, non un database per sempre. Il plugin dovrebbe aggiornare la registrazione all'avvio dell'app, alla ricarica 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 ascoltatore stabile id.
• notificationOpened Si registra l'ascoltatore durante l'avvio dell'app.
• Non si 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'

Inviare 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, incongruenza di prova, consenso falso, ID app non corrispondente.
Denegato il permesso	Denegato o non richiesto ancora il prompt del sistema operativo.
Statistiche in coda ma non inviate	Manca o è disabilitato il credenziale della piattaforma.
Statistiche inviate ma non ricevute	Il dispositivo è offline, l'OS sta rallentando, l'app è stata chiusa forzatamente o il token è invalido.
I log delle notifiche in primo piano ma nessun banner	L'app è in primo piano e deve mostrare la propria UI in-app.
Il background non esegue mai su iOS	Mancano le capacità, manca la delega dell'AppDelegate, l'app è stata chiusa forzatamente o l'OS sta rallentando.
La verifica dell'aggiornamento non fa nulla	L'integrazione dell'aggiornamento è disabilitata, non c'è un nuovo bundle, il canale è sbagliato o il modo di installazione è mal interpretato.
La badge si resetta	L'avvio dell'app code cancella le badge o le scritture locali e backend delle badge si contendono.

Prosegui dall'analisi di debug

Dopo che il dispositivo si è registrato e una notifica di test funziona, utilizza Iniziare per collegare le vette, la pianificazione della campagna e le verifiche di aggiornamento silenzioso nella tua app di produzione.