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

1. Verifique se a chave do servidor obtida do Firebase corresponde à chave do servidor registrada no portal do Azure.

   

2. 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.

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:

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.

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.

1. Na guia Visão geral, você pode ver uma exibição agregada de registros, notificações e erros por plataforma.

   

2. 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.

   

3. 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.

4. 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.