Diagnosticar notificações descartadas nos Hubs de Notificação do Azure
Uma pergunta comum sobre os Hubs de Notificação do Azure é como solucionar problemas quando as notificações de um aplicativo não aparecem em dispositivos cliente. Os clientes querem saber onde e por que as notificações foram descartadas e como corrigir o problema. Este artigo identifica por que as notificações podem ser descartadas ou não serem recebidas pelos dispositivos. Ele também explica como determinar a causa raiz.
É fundamental primeiro entender como os Hubs de Notificação enviam notificações por push para um dispositivo.
Em um fluxo de notificação de envio típico, a mensagem é enviada do back-end do aplicativo para os Hubs de Notificação. Os Hubs de Notificação processam todos os registros. Ele leva em consideração as tags e expressões de tag configuradas para determinar os destinos. Os alvos são os registros que precisam receber a notificação por push. Estes registos podem abranger qualquer uma das nossas plataformas suportadas: Android, Baidu (dispositivos Android na China), Fire OS (Amazon) iOS, Windows e Windows Phone.
Com as metas estabelecidas, os Hubs de Notificação enviam notificações por push para o serviço de notificação por push da plataforma do dispositivo. Os exemplos incluem o serviço Apple Push Notification (APNs) para iOS e macOS e o Firebase Cloud Messaging (FCM) para dispositivos Android. Os Hubs de Notificação enviam notificações divididas em vários lotes de registros. Ele se autentica com o respetivo serviço de notificação por push, com base nas credenciais definidas no portal do Azure, em Configurar Hub de Notificação. Em seguida, o serviço de notificação por push encaminha as notificações para os respetivos dispositivos cliente.
A etapa final da entrega de notificações é entre o serviço de notificação por push da plataforma e o dispositivo. A entrega de notificações pode falhar em qualquer um dos quatro estágios do processo de notificação por push (cliente, back-end do aplicativo, Hubs de Notificação e serviço de notificação por push da plataforma). Para obter mais informações sobre a arquitetura dos Hubs de Notificação, consulte Visão geral dos Hubs de Notificação.
Uma falha na entrega de notificações pode ocorrer durante a fase inicial de teste/preparação. Notificações descartadas neste estágio podem indicar um problema de configuração. Se ocorrer uma falha na entrega de notificações na produção, algumas ou todas as notificações podem ser descartadas. Um problema mais profundo de aplicativo ou padrão de mensagens é indicado neste caso.
A próxima seção analisa cenários em que as notificações podem ser descartadas, variando de comuns a raras.
Configuração incorreta dos Hubs de Notificação
Para enviar notificações para o respetivo serviço de notificação por push, os Hubs de Notificação devem autenticar-se no contexto do seu aplicativo. Você deve criar uma conta de desenvolvedor com o serviço de notificação da plataforma de destino (Microsoft, Apple, Google, etc.). Em seguida, você deve registrar seu aplicativo com o sistema operacional, onde você obtém um token ou chave que você usa para trabalhar com o PNS de destino.
Você deve adicionar credenciais de plataforma ao portal do Azure. Se nenhuma notificação estiver chegando ao dispositivo, a primeira etapa é garantir que as credenciais corretas estejam configuradas nos Hubs de Notificação. As credenciais devem corresponder ao aplicativo criado em uma conta de desenvolvedor específica da plataforma.
Para obter instruções passo a passo para concluir esse processo, consulte Introdução aos Hubs de Notificação do Azure.
Aqui estão algumas configurações incorretas comuns para verificar:
Localização do nome do hub de notificação
Verifique se o nome do hub de notificação (sem erros de digitação) é o mesmo em cada um destes locais:
- Onde se regista a partir do cliente
- Onde você envia notificações do back-end
- Onde você configurou as credenciais do serviço de notificação por push
Certifique-se de usar as cadeias de caracteres de configuração de assinatura de acesso compartilhado corretas no cliente e no back-end do aplicativo. Geralmente, você deve usar DefaultListenSharedAccessSignature no cliente e DefaultFullSharedAccessSignature no back-end do aplicativo. Isso concede permissões para enviar notificações aos Hubs de Notificação.
Configuração do APN
Você deve manter dois hubs diferentes: um para produção e outro para testes. Você deve carregar o certificado usado em um ambiente de área restrita para um hub separado do certificado/hub que você usará na produção. Não tente carregar diferentes tipos de certificados para o mesmo hub. Isso causará falhas de notificação.
Se você carregar inadvertidamente diferentes tipos de certificados para o mesmo hub, exclua o hub e comece de novo com um novo hub. Se, por algum motivo, você não puder excluir o hub, deverá pelo menos excluir todos os registros existentes do hub.
Configuração do FCM
Nota
Para obter informações sobre as etapas de descontinuação e migração do Firebase Cloud Messaging, consulte Migração do Google Firebase Cloud Messaging.
Verifique se a chave do servidor obtida do Firebase corresponde à chave do servidor registrada no portal do Azure.
Certifique-se de ter configurado a ID do projeto no cliente. Você pode obter o valor para ID do projeto no painel do Firebase.
Problemas de aplicação
Tags e expressões de tags
Se você usar tags ou expressões de tags para segmentar seu público, é possível que, ao enviar a notificação, nenhum destino seja encontrado. Este erro baseia-se nas etiquetas ou expressões de etiquetas especificadas na sua chamada de envio.
Reveja os seus registos para garantir que as etiquetas correspondem quando envia uma notificação. Em seguida, verifique o recebimento da notificação apenas dos clientes que têm esses registros.
Por exemplo, suponha que todos os seus registros nos Hubs de Notificação usem a tag "Política". Se você enviar uma notificação com a tag "Esportes", a notificação não será enviada para nenhum dispositivo. Um caso complexo pode envolver expressões de tag em que você se registrou usando "Tag A" ou "Tag B", mas segmentou "Tag A && Tag B". A seção de dicas de autodiagnóstico mais adiante no artigo mostra como revisar seus registros e suas tags.
Problemas de modelo
Se você usar modelos, certifique-se de seguir as diretrizes descritas em Modelos.
Registos inválidos
Se o hub de notificação tiver sido configurado corretamente e tags ou expressões de tags tiverem sido usadas corretamente, destinos válidos serão encontrados. As notificações devem ser enviadas a esses alvos. Em seguida, os Hubs de Notificação dispara vários lotes de processamento em paralelo. Cada lote envia mensagens para um conjunto de registros.
Nota
Como os Hubs de Notificação processam lotes em paralelo, a ordem em que as notificações são entregues não é garantida.
Os Hubs de Notificação são otimizados para um modelo de entrega de mensagens "no máximo uma vez". Tentamos a desduplicação, para que nenhuma notificação seja entregue mais de uma vez a um dispositivo. Os registros são verificados para garantir que apenas uma mensagem seja enviada por identificador de dispositivo antes de ser enviada ao serviço de notificação por push.
Cada lote é enviado para o serviço de notificação push, que por sua vez aceita e valida os registros. Durante esse processo, é possível que o serviço de notificação por push detete um erro com um ou mais registros em um lote. Em seguida, o serviço de notificação por push retorna um erro para os Hubs de Notificação e o processo é interrompido. O serviço de notificação por push descarta esse lote completamente. Isso é especialmente verdadeiro com APNs, que usa um protocolo de fluxo TCP.
Nesse caso, o registro com falha é removido do banco de dados. Em seguida, tentamos novamente a entrega de notificações para o resto dos dispositivos nesse lote.
Para obter mais informações de erro sobre a tentativa de entrega com falha em relação a um registro, você pode usar as APIs REST dos Hubs de Notificação por telemetria por mensagem: obter telemetria de mensagem de notificação e feedback PNS. Para obter um código de exemplo, consulte o exemplo Send REST.
Problemas do serviço de notificação por push
Depois que o serviço de notificação por push recebe a notificação, ele entrega a notificação ao dispositivo. Neste ponto, os Hubs de Notificação não têm controle sobre a entrega da notificação ao dispositivo.
Como os serviços de notificação da plataforma são robustos, as notificações tendem a chegar aos dispositivos em poucos segundos. Se o serviço de notificação por push estiver sendo limitado, os Hubs de Notificação aplicarão uma estratégia de back-off exponencial. Se o serviço de notificação por push permanecer inacessível por 30 minutos, há uma política em vigor para expirar e soltar as mensagens permanentemente.
Se um serviço de notificação por push tentar entregar uma notificação, mas o dispositivo estiver offline, a notificação será armazenada pelo serviço de notificação por push. É armazenado apenas por um período limitado de tempo. A notificação é entregue ao dispositivo quando o dispositivo fica disponível.
Cada aplicativo armazena apenas uma notificação recente. Se várias notificações forem enviadas enquanto um dispositivo estiver offline, cada nova notificação fará com que a última seja descartada. Manter apenas a notificação mais recente é chamado de coalescência em APNs e colapso em FCM. (O FCM usa uma chave de recolhimento.) Quando o dispositivo permanece offline por muito tempo, as notificações que foram armazenadas para o dispositivo são descartadas. Para obter mais informações, consulte Visão geral de APNs e Sobre mensagens FCM.
Com os Hubs de Notificação, você pode passar uma chave de coalescência por meio de um cabeçalho HTTP usando a API genérica SendNotification. Por exemplo, para o SDK do .NET, você usaria SendNotificationAsynco . A API SendNotification também usa cabeçalhos HTTP que são passados como é para o respetivo serviço de notificação por push.
Dicas de autodiagnóstico
Aqui estão os caminhos para diagnosticar a causa raiz das notificações descartadas nos Hubs de Notificação.
Verificar credenciais
Portal do desenvolvedor do serviço de notificação por push
Verifique as credenciais no respetivo portal do desenvolvedor do serviço de notificação por push (APNs, FCM, Serviço de Notificação do Windows e assim por diante). Para obter mais informações, consulte Tutorial: Enviar notificações para aplicativos da Plataforma Universal do Windows usando os Hubs de Notificação do Azure.
Portal do Azure
Para rever e fazer corresponder as credenciais com as que obteve no portal do programador do serviço de notificação por push, aceda ao separador Políticas de Acesso no portal do Azure.
Verificar registos
Visual Studio
No Visual Studio, você pode se conectar ao Azure por meio do Gerenciador de Servidores para exibir e gerenciar vários serviços do Azure, incluindo Hubs de Notificação. Esse atalho é útil principalmente para seu ambiente de desenvolvimento/teste.
Você pode visualizar e gerenciar todos os registros em seu hub. Os registros podem ser categorizados por plataforma, registro nativo ou modelo, tag, identificador de serviço de notificação push, ID de registro e data de validade. Também pode editar um registo nesta página. É especialmente útil para editar tags.
Clique com o botão direito do mouse no hub de notificação no Gerenciador de Servidores e selecione Diagnosticar.
Você verá a seguinte página:
Mude para a página Registos de Dispositivos:
Você pode usar a página Enviar teste para enviar uma mensagem de notificação de teste:
Nota
Use o Visual Studio para editar registros somente durante o desenvolvimento/teste e com um número limitado de registros. Se você precisar editar seus registros em massa, considere usar a funcionalidade de registro de exportação e importação descrita em Como: Exportar e modificar registros em massa.
Explorador do Service Bus
Muitos clientes usam o Service Bus Explorer para exibir e gerenciar seus hubs de notificação. O Service Bus Explorer é um projeto de código aberto.
Verificar notificações de mensagens
Portal do Azure
Para enviar uma notificação de teste para seus clientes sem ter um backup de serviço em execução, em SUPORTE + SOLUÇÃO de PROBLEMAS, selecione Enviar Teste.
Visual Studio
Você também pode enviar notificações de teste do Visual Studio.
Depurar notificações com falha e rever o resultado da notificação
EnableTestSend propriedade
Quando você envia uma notificação por meio dos Hubs de Notificação, a notificação é inicialmente enfileirada. Os Hubs de Notificação determinam os destinos corretos e, em seguida, enviam a notificação para o serviço de notificação por push. Se você estiver usando a API REST ou qualquer um dos SDKs de cliente, o retorno da chamada de envio significa apenas que a mensagem está enfileirada com os Hubs de Notificação. Ele não fornece informações sobre o que aconteceu quando os Hubs de Notificação eventualmente enviaram a notificação para o serviço de notificação por push.
Se a notificação não chegar ao dispositivo cliente, pode ter ocorrido um erro quando os Hubs de Notificação tentaram entregá-la ao serviço de notificação por push. Por exemplo, o tamanho da carga útil pode exceder o máximo permitido pelo serviço de notificação por push ou as credenciais configuradas nos Hubs de Notificação podem ser inválidas.
Para obter informações sobre erros do serviço de notificação por push, você pode usar a propriedade EnableTestSend . Essa propriedade é habilitada automaticamente quando você envia mensagens de teste do portal ou cliente do Visual Studio. Você pode usar essa propriedade para ver informações detalhadas de depuração e também por meio de APIs. Atualmente, você pode usá-lo no SDK do .NET. Ele será adicionado a todos os SDKs de cliente eventualmente.
Para usar a propriedade com a EnableTestSend chamada REST, acrescente um parâmetro de cadeia de caracteres de consulta chamado test ao final da chamada de envio. Por exemplo:
https://mynamespace.servicebus.windows.net/mynotificationhub/messages?api-version=2013-10&test
Exemplo do SDK do .NET
Veja um exemplo de como usar o SDK do .NET para enviar uma notificação pop-up (do sistema) nativa:
NotificationHubClient hub = NotificationHubClient.CreateClientFromConnectionString(connString, hubName);
var result = await hub.SendWindowsNativeNotificationAsync(toast);
Console.WriteLine(result.State);
No final da execução, result.State simplesmente declara Enqueued. Os resultados não fornecem nenhuma visão sobre o que aconteceu com sua notificação por push.
Em seguida, você pode usar a EnableTestSend propriedade Boolean. Use a propriedade enquanto inicializa NotificationHubClient para obter um status detalhado sobre erros de serviço de notificação por push que ocorrem quando a EnableTestSend notificação é enviada. A chamada de envio leva mais tempo para retornar porque primeiro precisa que os Hubs de Notificação entreguem a notificação ao serviço de notificação por 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);
}
Saída de exemplo
DetailedStateAvailable
windows
7619785862101227384-7840974832647865618-3
The Token obtained from the Token Provider is wrong
Essa mensagem indica que as credenciais configuradas nos Hubs de Notificação são inválidas ou que há um problema com os registros no hub. Exclua esse registro e deixe o cliente recriar o registro antes de enviar a mensagem.
Nota
O uso da EnableTestSend propriedade é fortemente limitado. Use esta opção apenas em um ambiente de desenvolvimento/teste e com um conjunto limitado de registros. As notificações de depuração são enviadas para apenas 10 dispositivos. Há também um limite de processamento de envios de depuração, de 10 por minuto. As notificações de depuração também são excluídas do SLA dos Hubs de Notificação do Azure.
Rever telemetria
Portal do Azure
No portal, você pode obter uma visão geral rápida de todas as atividades em seu hub de notificação.
Na guia Visão geral, você pode ver uma exibição agregada de registros, notificações e erros por plataforma.
Na guia Registro de atividades , você pode adicionar outras métricas específicas da plataforma para uma análise mais profunda. Você pode examinar especificamente os erros que são retornados quando os Hubs de Notificação tentam enviar a notificação para o serviço de notificação por push.
Na guia Visão geral, comece examinando Mensagens de entrada, Operações de registro e Notificações bem-sucedidas. Em seguida, vá para a guia por plataforma para revisar os erros específicos desse serviço de notificação por push.
Se as configurações de autenticação do hub de notificação estiverem incorretas, a mensagem Erro de autenticação PNS será exibida. É uma boa indicação para verificar as credenciais do serviço de notificação por push.
Acesso programático
Para obter mais informações sobre acesso programático, consulte Acesso programático.
Nota
Vários recursos relacionados à telemetria, como exportação e importação de registros e acesso de telemetria por meio de APIs, estão disponíveis apenas na camada de serviço Padrão. Se você tentar usar esses recursos da camada de serviço Gratuito ou Básico, receberá uma mensagem de exceção se usar o SDK. Você receberá um erro HTTP 403 (Proibido) se usar os recursos diretamente das APIs REST.
Para usar recursos relacionados à telemetria, primeiro verifique no portal do Azure se você está usando a camada de serviço Padrão.