Solução de problemas de notificações por push do WNS

Este tópico discute as etapas iniciais de solução de problemas que você deve executar ao enfrentar problemas com notificações de bloco, toast e bandeja, incluindo os vários métodos de notificação: notificações locais, por push, periódicas e agendadas.

Solução de problemas de erros específicos

Esta seção aborda alguns erros comuns que você pode encontrar ao trabalhar com notificações por push.

• Verificar os logs de eventos
• A notificação por push recebe uma resposta "200 OK", mas não é exibida
• A notificação por push retorna um código diferente de "200 OK"
• Erros ao tentar criar um canal de notificação por push

Verificar os logs de eventos

Se as notificações por push de blocos ou toast não estiverem sendo exibidas conforme o esperado, examine os logs de eventos.

• Se a notificação for recebida, mas não for mostrada: inicie o Visualizador de Eventos e examine o log Microsoft-Windows-TWinUI/Operacional em Aplicativos e Serviços\Microsoft\Windows\Apps.
• Se a notificação não for recebida: inicie o Visualizador de Eventos e examine o log operacional em Aplicativos e Serviços\Microsoft\Windows\PushNotifications-Platform.

A notificação por push recebe uma resposta "200 OK", mas não é exibida

Se o WNS (Serviços de Notificação por Push) do Windows retornar uma resposta "200 OK", ele entregará a notificação ao cliente se o cliente estiver online. Se você verificou que o cliente está online, mas não está exibindo a notificação, siga estas etapas:

• Causa: erros de XML no conteúdo da notificação.

  Corrigir: verifique a sintaxe XML básica e certifique-se de que o XML está completo e correto. Alguns pontos comuns de falha no conteúdo XML incluem o seguinte:

  • Case sensitivity. Nomes de marcas, nomes de atributo e valores de atributo são sensíveis a maiúsculas e minúsculas. Certifique-se de que seu XML tenha a caixa correta.
  • Um elemento de associação deve ser fornecido para cada formato de tile com suporte. Você deve fornecer um elemento de associação para cada um dos tamanhos de bloco que você suporta em cada notificação que enviar.
  • As cadeias de caracteres de texto não devem conter caracteres XML reservados. Por exemplo, você não pode colocar em itálico blocos ou cadeias de caracteres ao incluir as tags <i> e </i>. Se você pretende mostrar os caracteres literais "<i>", eles devem ser escapados corretamente. Para obter mais informações sobre caracteres de escape em XML, consulte Entidades de Caractere em XML eem XAML.
  • Os valores fornecidos para os atributos lang devem estar em conformidade com a especificação ITEF BCP 47 .
  • As cadeias de caracteres XML enviadas por meio de notificações por push devem usar a codificação UTF-8.
  • Se você incluir um elemento de imagem na sua carga XML com um atributo src não vazio, deverá incluir uma referência a uma imagem válida, ou a notificação será descartada.

• Causa: uso inadequado de parâmetros da API de notificação por push

  Corrigir: consulte a documentação da API no namespace Windows.Networking.PushNotifications para obter detalhes.

• Causa: o tipo de cabeçalho não corresponde ao conteúdo da notificação. Se o cabeçalho X-WNS-Type não estiver definido como um valor — tile, emblema ou toast — que corresponda ao modelo de notificação especificado no payload, a notificação não será exibida. Essa incompatibilidade causará um erro no cliente e a notificação será descartada.

  Corrigir: consulte cabeçalhos de solicitação e resposta do serviço de notificação por push para garantir que o servidor de aplicativos esteja usando o valor correto para o cabeçalho X-WNS-Type.

• Causa: o valor de TTL (tempo de vida útil), definido no cabeçalho X-WNS-TTL, é muito pequeno.

  Ajuste: forneça um valor TTL maior, ciente de que o valor é dado em segundos.

Se você ainda não vir sua notificação exibida depois de abordar os itens nas etapas anteriores, consulte as etapas de solução de problemas para notificações locais na seção deste tópico intitulada "A notificação de bloco local não é exibida" para obter mais sugestões.

A notificação por push retorna um código diferente de "200 OK"

Se o WNS não retornar "200 OK", sua notificação não será entregue ao cliente. Se o código de retorno estiver na faixa dos 400, você, como desenvolvedor, deverá ser capaz de corrigir o problema.

• A solicitação de notificação retorna "400 Solicitação Incorreta"
• A solicitação de notificação retorna "401 Não autorizado"
• A solicitação de notificação retorna "401 Não autorizado", o token expirou
• A solicitação de notificação retorna "403 Proibido"
• A solicitação de notificação retorna "404 Não Encontrado"
• A solicitação de notificação retorna "406 Não Aceitável"
• A solicitação de notificação retorna "410 Gone"

A solicitação de notificação retorna "400 Solicitação Incorreta"

• Causa: o uso de um ou mais cabeçalhos WNS pode estar incorreto ou a solicitação HTTP era inválida.

  Corrigir: consulte cabeçalhos de solicitação e resposta do serviço de notificação por push para garantir que o servidor de aplicativos esteja usando todos os cabeçalhos personalizados, conforme descrito.

A solicitação de notificação retorna "401 Não autorizado"

• Causa: o servidor do aplicativo deve usar o SID (Identificador de Segurança de Pacote) correto e a chave secreta fornecida a você quando o aplicativo foi registrado. Se você tiver alterado recentemente sua chave secreta no Painel da Windows Store, também precisará atualizar o servidor do aplicativo.

  Corrigir: visite o Windows Store Dashboard para verificar o SID e o segredo do pacote.

A solicitação de notificação retorna "401 Não autorizado", o token expirou

• Causa: um token de acesso tem um tempo de vida finito. Se você enviar uma notificação com um token de acesso expirado, as credenciais do servidor de aplicativo serão inválidas e a notificação não poderá ser enviada.

  Corrigir: Solicitar um novo token de acesso do WNS autenticando-se com o WNS usando seu Identificador de Segurança do Pacote (SID) e chave secreta. Para obter mais informações, consulte a Visão Geral dos Serviços de Notificação por Push do Windows (WNS)

A solicitação de notificação retorna "403 Proibido"

• Causa: esse erro ocorre quando o token de acesso que você apresentou não corresponde às credenciais necessárias para enviar notificações à URL do canal correspondente. Cada aplicativo deve ser registrado na Windows Store para receber credenciais para seu servidor de aplicativos. Para cada aplicativo, somente as credenciais fornecidas pela Windows Store podem ser usadas para enviar notificações para esse aplicativo e elas só podem ser usadas para esse aplicativo específico.

  Corrigir: faça login no Painel do Microsoft Store com sua conta de desenvolvedor. Selecione seu aplicativo e clique em "Recursos Avançados" –> "Gerenciar suas configurações de serviço de nuvem". Selecione "Identificar seu aplicativo" para ler instruções sobre como atualizar o manifesto do aplicativo para corresponder às credenciais do serviço de nuvem.

A solicitação de notificação retorna "404 Não Encontrado"

• Causa: esse erro normalmente significa que a URL do canal não está formada corretamente. A URL do canal nunca deve ser adulterada ou modificada quando você envia uma notificação ao WNS. A URL do canal sempre deve ser tratada como uma cadeia de caracteres opaca. Você nunca precisa examinar ou mesmo saber seu conteúdo.

  Correção: verifique se o código não está modificando a URL do canal alterando um ou mais de seus caracteres ou alterando sua codificação.

A solicitação de notificação retorna "406 Não Aceitável"

• Causa: o WNS tem políticas de proteção em vigor para impedir que aplicativos mal-intencionados afetem negativamente o serviço para outros usuários e desenvolvedores. Um número excessivo de notificações em um período de tempo muito curto pode resultar na remoção explícita de notificações do WNS.

  Correção: examine a frequência de notificação para ver se ela pode ser reduzida ou otimizada para produzir uma melhor experiência do usuário.

A solicitação de notificação retorna "410 Gone"

• Causa: a URL do canal expirou. Nenhuma outra notificação pode ser enviada até que seu aplicativo seja executado e solicite uma nova URL de canal.

  Corrigir: seu aplicativo da Windows Store deve solicitar uma URL de canal sempre que for iniciado. A URL do canal atribuída não tem a garantia de permanecer a mesma. Se a URL tiver sido alterada, o cliente deverá atualizar as informações em seu servidor de nuvem.

Erros ao tentar criar um canal de notificação por push

• Criar um canal de notificação resulta em um erro de ERROR_NO_NETWORK
• Criar um canal de notificação resulta em um erro de WPN_E_CLOUD_INCAPABLE
• Criar um canal de notificação resulta em um erro de WPN_E_INVALID_APP

Criar um canal de notificação resulta em um erro de ERROR_NO_NETWORK

• Causa: o WNS requer uma conexão com a Internet para criar um canal de notificação.

  Corrigir: verifique a conexão à Internet.

Criar um canal de notificação resulta em um erro de WPN_E_CLOUD_INCAPABLE

• Causa: seu aplicativo não declarou a funcionalidade da Internet no manifesto do aplicativo (package.appxmanifest).

  Corrigir: verifique se o manifesto do aplicativo declarou a funcionalidade da Internet. No editor de manifestos do Visual Studio, você encontrará essa opção na guia Recursos como Internet (Cliente). Para obter mais informações, consulte Recursos.

Criar um canal de notificação resulta em um erro de WPN_E_INVALID_APP

• Causa: Seu aplicativo deve usar um nome de pacote válido. Se você ainda não recebeu um, poderá obtê-lo por meio do portal da Windows Store em "Recursos Avançados".

  Corrigir: para obter detalhes sobre como recuperar um PKSID (Identificador de Segurança de Pacote) para seu aplicativo da Windows Store, consulte visão geral do WNS (Windows Push Notification Services).

Relatando um problema

Se você tentou as soluções sugeridas neste tópico e não resolveu o problema, poste uma mensagem nos fóruns da Microsoft para discuti-lo com desenvolvedores da Microsoft e outras partes interessadas.

Para notificações por push, além de uma descrição do problema, você pode ser solicitado a fornecer a URL do canal e um exemplo da resposta recebida do WNS, incluindo os códigos de erro HTTP e cabeçalhos HTTP. Há cabeçalhos específicos que o servidor de aplicativos deve estar registrando em log ao relatar um problema. Para obter mais informações, consulte solicitação de serviço de notificação por push, e cabeçalhos de resposta.