Diagnosticare le notifiche eliminate in Hub di notifica di Azure

Una domanda comune su Hub di notifica di Azure è come risolvere i problemi relativi alla visualizzazione delle notifiche da un'applicazione nei dispositivi client. I clienti vogliono sapere dove e perché le notifiche sono state eliminate e come risolvere il problema. Questo articolo illustra i motivi per cui le notifiche possono essere eliminate o non essere ricevute dai dispositivi. Spiega anche come determinare la causa radice.

È prima di tutto fondamentale capire come viene eseguito il push delle notifiche a un dispositivo da Hub di notifica.

In un flusso tipico di invio delle notifiche, il messaggio viene inviato dal back-end dell'applicazione ad Hub di notifica. Hub di notifica elabora tutte le registrazioni. Tiene conto dei tag configurati e delle espressioni di tag per determinare le destinazioni. Le destinazioni sono le registrazioni che devono ricevere la notifica push. Queste registrazioni possono estendersi su qualsiasi piattaforma supportata: Android, Baidu (dispositivi Android in Cina), Fire OS (Amazon) iOS, Windows e Windows Telefono.

Con le destinazioni stabilite, Hub di notifica esegue il push delle notifiche al servizio di notifica push per la piattaforma del dispositivo. Gli esempi includono il servizio Apple Push Notification (APN) per iOS e macOS e Firebase Cloud Messaging (FCM) per i dispositivi Android. Hub di notifica esegue il push delle notifiche suddivise in più batch di registrazioni. Esegue l'autenticazione con il rispettivo servizio di notifica push, in base alle credenziali impostate nel portale di Azure, in Configura hub di notifica. Il servizio di notifica push inoltra quindi le notifiche ai dispositivi client corrispondenti.

La fase finale del recapito delle notifiche è tra il servizio di notifica push della piattaforma e il dispositivo. Il recapito delle notifiche può avere esito negativo in una delle quattro fasi del processo di notifica push (client, back-end dell'applicazione, Hub di notifica e servizio di notifica push della piattaforma). Per altre informazioni sull'architettura di Hub di notifica, vedere Panoramica dell'Hub di notifica.

Un errore di recapito delle notifiche potrebbe verificarsi durante la fase iniziale di test/gestione temporanea. Le notifiche non recapitate in questa fase potrebbero indicare un problema di configurazione. Se si verifica un errore di recapito delle notifiche nell'ambiente di produzione, alcune o tutte le notifiche potrebbero essere eliminate. In questo caso viene indicato un problema di modello di messaggistica o applicazione più approfondito.

La sezione successiva esamina gli scenari in cui le notifiche potrebbero essere eliminate, che vanno da comuni a rare.

Configurazione errata di Hub di notifica

Per inviare notifiche al rispettivo servizio di notifica push, Hub di notifica deve autenticarsi nel contesto dell'applicazione. È necessario creare un account per sviluppatore con il servizio di notifica della piattaforma di destinazione (Microsoft, Apple, Google e così via). È quindi necessario registrare l'applicazione con il sistema operativo in cui si ottiene un token o una chiave che si usa per lavorare con il PNS di destinazione.

È necessario aggiungere le credenziali della piattaforma nel portale di Azure. Se nessuna notifica raggiunge il dispositivo, il primo passaggio consiste nel assicurarsi che le credenziali corrette siano configurate in Hub di notifica. Le credenziali devono corrispondere all'applicazione creata con un account sviluppatore specifico della piattaforma.

Per istruzioni dettagliate per eseguire questo processo, vedere Introduzione ad Hub di notifica di Azure.

Ecco alcuni errori di configurazione comuni:

Percorso del nome dell'hub di notifica

Assicurarsi che il nome dell'hub di notifica (privo di errori di digitazione) sia uguale in ognuna di queste posizioni:

• Posizione di registrazione dal client
• Dove si inviano notifiche dal back-end
• Posizione in cui sono state configurate le credenziali del servizio di notifica push

Assicurarsi di usare le stringhe di configurazione corrette della firma di accesso condiviso nel client e nel back-end dell'applicazione. In genere, è necessario usare DefaultListenSharedAccessSignature nel client e DefaultFullSharedAccessSignature nel back-end dell'applicazione. In questo modo vengono concesse le autorizzazioni per l'invio di notifiche a Hub di notifica.

Configurazione APN

È necessario mantenere due hub diversi: uno per la produzione e un altro per i test. È necessario caricare il certificato usato in un ambiente sandbox in un hub separato rispetto al certificato o all'hub che verrà usato nell'ambiente di produzione. Non provare a caricare tipi diversi di certificati nello stesso hub. Causerà errori di notifica.

Se si caricano inavvertitamente diversi tipi di certificati nello stesso hub, è necessario eliminare l'hub e iniziare a usare un nuovo hub. Se per qualche motivo non è possibile eliminare l'hub, è necessario eliminare almeno tutte le registrazioni esistenti dall'hub.

Configurazione di FCM

Nota

Per informazioni sui passaggi di deprecazione e migrazione di Firebase Cloud Messaging, vedere Migrazione di Google Firebase Cloud Messaging.

1. Assicurarsi che la chiave del server ottenuta da Firebase corrisponda alla chiave del server registrata nel portale di Azure.

   

2. Assicurarsi di aver configurato l'ID progetto nel client. È possibile ottenere il valore per ID progetto dal dashboard Firebase.

   

Problemi relativi all'applicazione

Tag ed espressioni tag

Se si usano tag o espressioni di tag per segmentare il pubblico, è possibile che quando si invia la notifica, non viene trovata alcuna destinazione. Questo errore si basa sui tag o sulle espressioni di tag specificate nella chiamata di invio.

Esaminare le registrazioni per assicurarsi che i tag corrispondano quando si invia una notifica. Verificare quindi la ricevuta di notifica solo dai client che dispongono di tali registrazioni.

Si supponga, ad esempio, che tutte le registrazioni con Hub di notifica usino il tag "Politica". Se si invia quindi una notifica con il tag "Sports", la notifica non verrà inviata ad alcun dispositivo. Un caso complesso può comportare espressioni di tag in cui è stata registrata usando "Tag A" o "Tag B", ma è stato assegnato "Tag A && Tag B". La sezione Suggerimenti per la diagnosi automatica più avanti nell'articolo illustra come esaminare le registrazioni e i relativi tag.

Problemi relativi ai modelli

Se si usano modelli, assicurarsi di seguire le indicazioni riportate in Modelli.

Registrazioni non valide

Se l'hub di notifica è stato configurato correttamente e sono stati usati correttamente tag o espressioni di tag, vengono trovate destinazioni valide. Le notifiche devono essere inviate a queste destinazioni. Hub di notifica attiva quindi vari batch di elaborazione in parallelo. Ogni batch invia messaggi a un set di registrazioni.

Nota

Poiché Hub di notifica elabora i batch in parallelo, l'ordine in cui vengono recapitate le notifiche non è garantito.

Hub di notifica è ottimizzato per un modello di recapito dei messaggi "at-most-once". che comporta un tentativo di deduplicazione per fare in modo che nessuna notifica venga recapitata più di una volta a un dispositivo. Le registrazioni vengono controllate per assicurarsi che venga inviato un solo messaggio per identificatore di dispositivo prima che venga inviato al servizio di notifica push.

Ogni batch viene inviato al servizio di notifica push, che a sua volta accetta e convalida le registrazioni. Durante questo processo, è possibile che il servizio di notifica push rilevi un errore con una o più registrazioni in un batch. Il servizio di notifica push restituisce quindi un errore a Hub di notifica e il processo si arresta. Il servizio di notifica push elimina completamente tale batch. Ciò vale soprattutto per le APN, che usano un protocollo di flusso TCP.

In questo caso, la registrazione di errore viene rimossa dal database. Viene quindi eseguito un ulteriore tentativo di recapito per il resto dei dispositivi nel batch.

Per ottenere altre informazioni sugli errori sul tentativo di recapito non riuscito rispetto a una registrazione, è possibile usare le API REST di Hub di notifica per dati di telemetria per messaggio: ottenere i dati di telemetria dei messaggi di notifica e il feedback PNS. Per un esempio di codice, vedere l'esempio REST per l'invio.

Problemi del servizio di notifica push

Dopo che il servizio di notifica push riceve la notifica, recapita la notifica al dispositivo. A questo punto, Hub di notifica non ha alcun controllo sul recapito della notifica al dispositivo.

Poiché i servizi di notifica della piattaforma sono affidabili, le notifiche tendono a raggiungere i dispositivi in pochi secondi. Se il servizio di notifica push è limitato, Hub di notifica applica una strategia con backoff esponenziale. Se il servizio di notifica push rimane non raggiungibile per 30 minuti, è previsto un criterio per la scadenza e l'eliminazione definitiva dei messaggi.

Se un servizio di notifica push tenta di recapitare una notifica ma il dispositivo è offline, la notifica viene archiviata dal servizio di notifica push. Viene archiviato solo per un periodo di tempo limitato. e viene recapitata al dispositivo quando ritorna disponibile.

Ogni app archivia una sola notifica recente. Se vengono inviate più notifiche mentre un dispositivo è offline, ogni nuova notifica causa l'eliminazione dell'ultimo. Mantenere solo la notifica più recente viene chiamata unione nelle APN e compressione in FCM. FCM usa una chiave di compressione. Quando il dispositivo rimane offline per molto tempo, le notifiche archiviate per il dispositivo vengono rimosse. Per altre informazioni, vedere Panoramica dei nomi APN e Informazioni sui messaggi FCM.

Con Hub di notifica è possibile passare una chiave di unione tramite un'intestazione HTTP usando l'API SendNotification generica. Ad esempio, SendNotificationAsync per .NET SDK. L'API SendNotification accetta anche le intestazioni HTTP passate così come avviene per il rispettivo servizio di notifica push.

Suggerimenti per l'autodiagnosi

Ecco i percorsi per diagnosticare la causa radice delle notifiche eliminate in Hub di notifica.

Verificare le credenziali

Portale per sviluppatori del servizio di notifica push

Verificare le credenziali nel rispettivo portale per sviluppatori del servizio di notifica push corrispondente (APN, FCM, il servizio di notifica di Windows e così via). Per altre informazioni, vedere Esercitazione: Inviare notifiche alle app piattaforma UWP (Universal Windows Platform) usando Hub di notifica di Azure.

Azure portal

Per esaminare e associare le credenziali a quelle ottenute dal portale per sviluppatori del servizio di notifica push, passare alla scheda Criteri di accesso nella portale di Azure.

Verificare le registrazioni

Visual Studio

In Visual Studio è possibile connettersi ad Azure tramite Esplora server per visualizzare e gestire più servizi di Azure, inclusi Hub di notifica. Questo collegamento è utile principalmente per l'ambiente di sviluppo/test.

È possibile visualizzare e gestire tutte le registrazioni nell'hub. Le registrazioni possono essere classificate per piattaforma, registrazione nativa o modello, tag, identificatore del servizio di notifica push, ID registrazione e data di scadenza. È anche possibile modificare una registrazione in questa pagina. È particolarmente utile per la modifica dei tag.

Fare clic con il pulsante destro del mouse sull'hub di notifica in Esplora server e scegliere Diagnostica.

Viene visualizzata la pagina seguente:

Passare alla pagina Registrazioni dispositivo:

È possibile usare la pagina Invio test per inviare un messaggio di notifica di test:

Nota

Usare Visual Studio per modificare le registrazioni solo durante lo sviluppo/test e con un numero limitato di registrazioni. Se è necessario modificare le registrazioni in blocco, è consigliabile usare la funzionalità di esportazione e importazione della registrazione descritta in Procedura: Esportare e modificare le registrazioni in blocco.

Service Bus Explorer

Molti clienti usano bus di servizio Explorer per visualizzare e gestire gli hub di notifica. Service Bus Explorer è un progetto open source.

Verificare le notifiche di messaggi

Azure portal

Per inviare una notifica di prova ai client senza un back-end di servizio attivo e in esecuzione, in Supporto e risoluzione dei problemi selezionare Invio di prova.

Visual Studio

È anche possibile inviare notifiche di prova da Visual Studio.

Eseguire il debug di notifiche non riuscite ed esaminare l'esito della notifica

Proprietà EnableTestSend

Quando si invia una notifica tramite Hub di notifica, la notifica viene inizialmente accodata. Hub di notifica determina le destinazioni corrette e quindi invia la notifica al servizio di notifica push. Se si usa l'API REST o uno degli SDK client, la restituzione della chiamata di invio significa solo che il messaggio viene accodato con Hub di notifica. Non fornisce informazioni dettagliate su ciò che è accaduto quando Hub di notifica ha inviato la notifica al servizio di notifica push.

Se la notifica non arriva al dispositivo client, potrebbe essersi verificato un errore quando Hub di notifica ha tentato di recapitarlo al servizio di notifica push. Ad esempio, le dimensioni del payload potrebbero superare il massimo consentito dal servizio di notifica push o le credenziali configurate in Hub di notifica potrebbero non essere valide.

Per ottenere informazioni dettagliate sugli errori del servizio di notifica push, è possibile usare la proprietà EnableTestSend. Questa proprietà viene abilitata automaticamente quando si inviano messaggi di prova dal portale o dal client di Visual Studio È possibile usare questa proprietà per visualizzare informazioni dettagliate sul debug e anche tramite le API. Attualmente, è possibile usarla in .NET SDK. Verrà aggiunto a tutti gli SDK client.

Per usare la proprietà EnableTestSend con la chiamata REST, aggiungere un parametro di stringa di query denominato test alla fine della chiamata di invio. Ad esempio:

https://mynamespace.servicebus.windows.net/mynotificationhub/messages?api-version=2013-10&test

Esempio di .NET SDK

Di seguito è riportato un esempio di uso di .NET SDK per inviare una notifica popup nativa:

NotificationHubClient hub = NotificationHubClient.CreateClientFromConnectionString(connString, hubName);
var result = await hub.SendWindowsNativeNotificationAsync(toast);
Console.WriteLine(result.State);

Al termine dell'esecuzione, result.State indica semplicemente Enqueued. I risultati non offrono alcuna informazione su quanto accaduto alla notifica push.

Successivamente, è possibile usare la proprietà booleana EnableTestSend. Usare la proprietà EnableTestSend mentre si inizializza NotificationHubClient per ottenere uno stato dettagliato degli errori del servizio di notifica push che si verificano quando viene inviata la notifica. La chiamata di invio richiede più tempo per la restituzione perché richiede prima hub di notifica per recapitare la notifica al servizio di notifica push.

    bool enableTestSend = true;
    NotificationHubClient hub = NotificationHubClient.CreateClientFromConnectionString(connString, hubName, enableTestSend);

    var outcome = await hub.SendWindowsNativeNotificationAsync(toast);
    Console.WriteLine(outcome.State);

    foreach (RegistrationResult result in outcome.Results)
    {
        Console.WriteLine(result.ApplicationPlatform + "\n" + result.RegistrationId + "\n" + result.Outcome);
    }

Output di esempio

DetailedStateAvailable
windows
7619785862101227384-7840974832647865618-3
The Token obtained from the Token Provider is wrong

Questo messaggio indica che le credenziali configurate in Hub di notifica non sono valide o che si è verificato un problema con le registrazioni nell'hub. Eliminare questa registrazione e consentire al client di ricreare la registrazione prima di inviare il messaggio.

Nota

L'uso della proprietà EnableTestSend è molto limitato. Usare questa opzione solo in un ambiente di sviluppo/test e con un set limitato di registrazioni. Le notifiche di debug vengono inviate solo a 10 dispositivi. Esiste anche un limite per l'elaborazione degli invii di debug, a 10 al minuto. Le notifiche di debug vengono escluse anche dal contratto di servizio di Hub di notifica di Azure.

Esaminare i dati di telemetria

Azure portal

Nel portale è possibile ottenere una rapida panoramica di tutte le attività nell'hub di notifica.

1. Nella scheda Panoramica è disponibile una visualizzazione aggregata di registrazioni, notifiche ed errori in base alla piattaforma.

   

2. Nella scheda Log attività è possibile aggiungere altre metriche specifiche della piattaforma per un'analisi più approfondita. È possibile esaminare in modo specifico gli errori restituiti quando Hub di notifica tenta di inviare la notifica al servizio di notifica push.

   

3. Nella scheda Panoramica esaminare i messaggi in arrivo, le operazioni di registrazione e le notifiche riuscite. Passare quindi alla scheda per piattaforma per esaminare gli errori specifici del servizio di notifica push.

4. Se le impostazioni di autenticazione per l'hub di notifica non sono corrette, viene visualizzato il messaggio Errore di autenticazione PNS. È una buona indicazione controllare le credenziali del servizio di notifica push.

Accesso programmatico

Per altre informazioni sull'accesso a livello di codice, vedere Accesso a livello di codice.

Nota

Diverse funzionalità correlate alla telemetria, come l'esportazione e importazione di registrazioni e l'accesso ai dati di telemetria tramite le API, sono disponibili solo con il livello di servizio Standard. Se si tenta di usare queste funzionalità dal livello di servizio Gratuito o Basic, verrà visualizzato un messaggio di eccezione se si usa l'SDK. Se si usano le funzionalità direttamente dalle API REST, verrà visualizzato un errore HTTP 403 (Accesso negato).

Per usare le funzionalità correlate alla telemetria, assicurarsi prima di tutto nella portale di Azure che si sta usando il livello di servizio Standard.