Diagnosticar notificações removidas 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 no dispositivos cliente. Os clientes querem saber onde e por que as notificações são removidas, e como corrigir o problema. Este artigo identifica o motivo pelo qual as notificações podem ser removidas ou não recebidas pelos dispositivos. Ele também explica como determinar a causa raiz.

É fundamental compreender primeiro como os Hubs de Notificação efetua push das notificações para um dispositivo.

Em um fluxo de envio de notificação típico, a mensagem é enviada do back-end do aplicativo para os Hubs de Notificação. Os Hubs de Notificação processam todas as notificações. Ele leva em conta as marcas configuradas e as expressões de marca para determinar os destinos. Destinos são os registros que precisam receber a notificação por push. Esses registros podem abranger qualquer uma das plataformas compatíveis: Android, Baidu (dispositivos Android na China), Fire OS (Amazon) iOS, Windows e Windows Phone.

Com os destinos estabelecidos, os Hubs de Notificação efetuam push nas notificações para o serviço de notificação por push para a plataforma do dispositivo. Alguns exemplos são o serviço APNs (Apple Push Notification Service) para iOS e macOS, e FCM (Firebase Cloud Messaging) para dispositivos Android. Os Hubs de Notificação efetuam push de notificações divididas em diversos lotes de registros. Eles são autenticados com o respectivo serviço de notificação por push com base nas credenciais que você definir no Portal do Azure, em Configurar Hub de Notificação. O serviço de notificação por push encaminha as notificações para os respectivos dispositivos cliente.

O segmento final da entrega da notificação está entre o serviço de notificação por push da plataforma e o dispositivo. A entrega de notificação pode falhar em qualquer um dos quatro estágios no processo de notificação por push (cliente, back-end do aplicativo, Hubs de Notificação e o 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.

Pode ocorrer uma falha ao entregar as notificações durante a fase inicial de teste/preparo. Notificações removidas neste estágio podem indicar um problema de configuração. Se ocorrer falha na entrega das notificações em produção, algumas ou todas as notificações poderão ser removidas. Nesse caso, há indicação de um problema de aplicativo ou padrão de mensagens mais profundo.

A próxima seção examina os cenários em que as notificações poderão ser removidas, variando desde casos comuns aos casos raros.

Configuração incorreta dos Hubs de Notificação

Para enviar notificações ao respectivo serviço de notificação por push, os Hubs de Notificação devem se autenticar no contexto do 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 no qual você obtém um token ou chave que você usa para trabalhar com o PNS de destino.

Você precisa adicionar as credenciais da plataforma para o Portal do Azure. Se nenhuma notificação está acessando o dispositivo, a primeira etapa é garantir que as credenciais corretas sejam configuradas nos Hubs de Notificação. As credenciais precisam corresponder ao aplicativo que é criado em uma conta de desenvolvedor específica da plataforma.

Para ver instruções passo a passo para concluir esse processo, consulte Introdução aos Hubs de Notificações do Microsoft Azure.

Aqui estão algumas configurações incorretas comuns para observar:

Local do nome do hub de notificações

Verifique se o nome do seu hub de notificação (sem erros de grafia) é o mesmo em todos esses locais:

• Onde você registra do cliente
• Para onde enviar notificações do back-end
• Onde você configurou as credenciais do serviço de notificação por push

Verifique se você usou as cadeias de caracteres de configuração de assinatura de acesso compartilhadas corretas no cliente e no back-end do aplicativo. Em geral, 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 de APN

Você deve manter dois hubs diferentes: um para produção e outro para testes. É preciso carregar o certificado que você pretende usar no ambiente de área restrita para um hub separado do certificado/hub que você usará na produção. Não tente carregar tipos diferentes de certificados para o mesmo hub. Isso causará falhas de notificação.

Caso você inadvertidamente carregue tipos diferentes de certificados para o mesmo hub, você deverá excluir o hub e começar do zero com um novo hub. Se não for possível excluir o hub por algum motivo, você deverá ao menos excluir todos os registros existentes do hub.

Configuração de FCM

Observação

Para obter informações sobre as etapas de substituição e migração do Firebase Cloud Messaging, confira Migração do Google Firebase Cloud Messaging.

1. Verifique se a chave do servidor obtida do Firebase corresponde à chave de servidor que você registrou no Portal do Azure.

   

2. Verifique se você configurou a ID do projeto no cliente. Você pode obter o valor da ID do projeto do painel do Firebase.

   

Problemas de aplicativos

Marcas e expressões de marca

Se você usa marcas ou expressões de marca para segmentar seu público-alvo, é possível que, ao enviar a notificação, nenhum destino seja encontrado. Esse erro se baseia nas marcas especificadas ou nas expressões de marca em sua chamada de envio.

Examine os registros para garantir que as marcas correspondem ao enviar uma notificação. Em seguida, verifique o recebimento da notificação somente de clientes que têm esses registros.

Por exemplo, suponha que todos os seus registros com Hubs de Notificação do Microsoft Azure usem a marca "Política". Se você enviar uma notificação com a marca "Esportes", a notificação não será enviada para nenhum dispositivo. Um caso complexo pode envolver expressões de marca em que você se registrou usando "Tag A" ou "Tag B", mas você 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 do modelo

Se você usar modelos, siga as diretrizes descritas em Modelos.

Registros inválidos

Se o hub de notificação foi configurado corretamente, e as marcas ou expressões de marca foram usadas corretamente, destinos válidos serão encontrados. As notificações devem ser enviadas para esses destinos. Os Hubs de Notificação, em seguida, disparam vários lotes de processamento em paralelo. Cada lote envia mensagens para um conjunto de registros.

Observação

Como os Hubs de Notificação processam lotes em paralelo, a ordem na qual as notificações são entregues não é garantida.

Os Hubs de Notificação foram otimizados para um modelo de entrega de mensagens “no máximo uma vez”. Tentamos realizar uma eliminação de duplicação para que nenhuma notificação seja entregue mais de uma vez para um dispositivo. Os registros são verificados para garantir que somente uma mensagem seja enviada por identificador de dispositivo antes de enviar a mensagem para o serviço de notificação por push.

Cada lote é enviado para o serviço de notificação por push, que, por sua vez, aceita e valida os registros. Durante esse processo, é possível que o serviço de notificação por push detecte um erro com um ou mais registros em um lote. O serviço de notificação por push retornará um erro para os Hubs de Notificação e o processo será interrompido. O serviço de notificação por push remove esse lote completamente. Isso é especialmente verdadeiro com APNs, que usam um protocolo de fluxo de TCP.

Nesse caso, o registro com falha será removido do banco de dados. Em seguida, tentamos entregar a notificação novamente para o restante dos dispositivos nesse lote.

Para obter mais informações de erro sobre a tentativa de entrega com falha em um registro, use as APIs REST dos Hubs de Notificação: Por Telemetria de Mensagem: obter telemetria de mensagem de notificação e Comentários do PNS. Para obter o código de exemplo, consulte o Exemplo de envio de 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 a entrega para o dispositivo. Neste ponto, os Hubs de Notificação não têm controle sobre a entrega da notificação para o dispositivo.

Como os serviços de notificação de plataforma são robustos, as notificações tendem a acessar os dispositivos dentro de alguns segundos. Se o serviço de notificação por push realiza limitação, os Hubs de Notificação aplicam uma estratégia de retirada exponencial. Se o serviço de notificação por push permanece inacessível por 30 minutos, há uma política em vigor para expirar e remover essas mensagens permanentemente.

Se um serviço de notificação por push tenta entregar uma notificação, mas o dispositivo está offline, a notificação é armazenada pelo serviço. Ele é armazenado apenas por um período limitado de tempo. A notificação é entregue ao dispositivo quando ele estiver disponível.

Cada aplicativo armazena apenas uma notificação recente. Se várias notificações forem enviadas quando o dispositivo estiver offline, cada nova notificação fará com que a última seja descartada. A manutenção somente da notificação mais recente é chamada de união nos APNs e recolhimento em FCM. (O FCM usa uma chave de recolhimento.) Quando o dispositivo permanecer offline por um longo tempo, as notificações que estavam armazenadas para ele serão descartadas. Para obter mais informações, consulte Visão geral de APNs e Sobre mensagens do FCM.

Com os Hubs de Notificação, você pode passar uma chave de união por meio de um cabeçalho HTTP usando a API SendNotification genérica. Por exemplo, para o SDK do .NET, você usaria SendNotificationAsync. A API SendNotification também usa cabeçalhos HTTP que são passados no estado em que se encontram para o respectivo serviço de notificação por push.

Dicas de autodiagnóstico

Estes são os caminhos para diagnosticar a causa raiz da remoção de notificações em Hubs de Notificação.

Verifique as credenciais

Portal do desenvolvedor do serviço de notificação por push

Verifique as credenciais no respectivo 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 Hubs de Notificação do Azure.

Portal do Azure

Para examinar e corresponder as credenciais àquelas obtidas do portal do desenvolvedor do serviço de notificação por push, acesse a guia Políticas de Acesso no portal do Azure.

Verificar registros

Visual Studio

No Visual Studio, poderá se conectar ao Azure e por meio do Gerenciador de Servidores para exibir e gerenciar vários serviços do Azure, incluindo os Hubs de Notificação. Esse atalho é útil principalmente para seu ambiente de desenvolvimento e teste.

Você pode exibir e gerenciar todos os registros em seu hub. Os registros podem ser categorizados por plataforma, registro nativo ou de modelo, marcas, identificador do serviço de notificação por push, ID de registro e data de validade. Também é possível editar um registro nesta página. Isso é especialmente útil para editar marcas.

Clique com o botão direito do mouse no hub de notificação em Gerenciador de Servidorese selecione Diagnosticar.

Você verá o seguinte:

Alterne para a página de Registros do Dispositivo:

Você pode usar a página de Envio de Teste para enviar uma mensagem de notificação de teste:

Observação

Use o Visual Studio para editar os registros somente durante o desenvolvimento e teste, e com um número limitado de registros. Se for necessário editar seus registros em massa, considere usar a funcionalidade de exportar e importar registros descrita em Como exportar e modificar registros em massa.

Service Bus Explorer

Muitos clientes usam o Service Bus Explorer para exibir e gerenciar o hub de notificação. O Gerenciador de Barramento de Serviço é um projeto de software livre.

Verificar as notificações de mensagem

Portal do Azure

Para enviar uma notificação de teste para seus clientes sem precisar de um serviço de back-end em funcionamento, em SUPORTE + SOLUÇÃO DE PROBLEMAS, selecione Envio de Teste.

Visual Studio

Você também pode enviar notificações de teste do Visual Studio.

Depurar notificações com falha e examinar o resultado da notificação

Propriedade EnableTestSend

Quando você envia uma notificação por meio de Hubs de Notificação, ela é 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 SDK cliente, o retorno da sua chamada de envio significará apenas que a mensagem foi enfileirada com os Hubs de Notificação. Não é dada nenhuma informação sobre o que aconteceu quando os Hubs de Notificação eventualmente a enviaram para o serviço de notificação por push.

Caso a notificação não chegue ao dispositivo cliente, pode ter ocorrido um erro quando os Hubs de Notificação tentaram entregar a mensagem para o serviço de notificação por push. Por exemplo, o tamanho do conteúdo poderá exceder o máximo permitido pelo serviço de notificação por push, ou as credenciais configuradas em 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 do cliente do Visual Studio. Você pode usar essa propriedade para ver informações detalhadas de depuração, e também por meio das APIs. No momento, é possível usá-la no SDK do .NET. Eventualmente, ela será adicionada a todos os SDKs de cliente.

Para usar a propriedade EnableTestSend com a chamada REST, acrescente um parâmetro de cadeia de consulta chamado test ao final da sua chamada de envio. Por exemplo:

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

Exemplo (SDK do .NET)

Veja este exemplo de como usar o SDK do .NET para enviar uma notificação de pop-up nativo (notificação do sistema):

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 informação sobre o que aconteceu com a notificação por push.

Em seguida, você pode usar a propriedade booliana EnableTestSend. Use a propriedade EnableTestSend ao iniciar NotificationHubClient para obter um status detalhado sobre os erros do serviço de notificação por push que ocorrem quando a notificação é enviada. A chamada de envio leva um tempo adicional para retornar porque ela primeiro precisa que os Hubs de Notificação entreguem a notificação para o 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

Esta 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 permita que o cliente recrie o registro antes de enviar a mensagem.

Observação

O uso da propriedade EnableTestSend é extremamente limitado. Use esta opção somente em um ambiente de desenvolvimento e teste, e com um conjunto limitado de registros. As notificações de depuração são enviadas para apenas 10 dispositivos. Também há 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.

Telemetria de revisão

Portal do Azure

No portal, é possível obter uma visão geral rápida de todas as atividades no seu hub de notificação.

1. Na guia Visão geral, é possível ver uma exibição agregada de registros, notificações e erros por plataforma.

   

2. Na guia Log 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 retornarem 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 as Mensagens de entrada, Operações de registro e Notificações bem-sucedidas. Em seguida, acesse a guia por plataforma para examinar os erros que são específicos desse serviço de notificação por push.

4. Se as configurações de autenticação para o hub de notificação estiverem incorretas, a mensagem Erro de autenticação do 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.

Observação

Vários recursos relacionados à telemetria, como exportar e importar os registros e acesso à telemetria por meio de APIs, estão disponíveis apenas na camada de serviço Standard. Se você tentar usar esses recursos nas camadas de serviço Gratuita ou Básica, receberá uma mensagem de exceção se você usar o SDK. Usar os recursos diretamente das APIs REST retornará o erro HTTP 403 (Proibido).

Para usar os recursos relacionados à telemetria, verifique primeiro no Portal do Azure se você está usando a camada de serviço Standard.