Como solicitar, criar e salvar um canal de notificação (HTML)

Artigo
12/12/2015

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

Observação Não está usando JavaScript? Veja Como solicitar, criar e salvar um canal de notificação (XAML).

Você pode abrir um URI (Uniform Resouce Identifier) do canal, por meio do qual seu aplicativo pode receber notificações por push. Desse modo, você pode enviar o canal ao servidor que o usa para enviar notificações por push e fechá-lo quando não precisar mais dele. Um canal é um endereço exclusivo que representa um usuário único em um dispositivo único para um aplicativo específico ou um bloco secundário.

Você deverá solicitar um novo canal cada vez que o seu aplicativo for lançado e atualizar o servidor de nuvem quando o URI mudar. Para saber mais detalhes, veja Comentários.

Importante Canais de notificação expiram automaticamente depois de 30 dias.

O que você precisa saber

Tecnologias

Windows Runtime

Pré-requisitos

Um conhecimento prático dos termos e conceitos de bloco e notificação, além de XML. Este tópico também supõe que você saiba como criar um aplicativo da Windows Store básico em JavaScript usando APIs do Tempo de Execução do Windows.
Familiaridade com conceitos, requisitos e operação de notificação por push e Serviços de Notificação por Push do Windows (WNS). Eles são abordados na Visão geral de notificações por push do Windows (WNS).

Instruções

Etapa 1: Solicitar um URI de canal

Este exemplo solicita um URI de canal. A solicitação é feita para a Plataforma de Cliente de Notificações que, por sua vez, solicita o URI de canal dos Serviços de Notificação por Push do Windows (WNS). Quando a solicitação é concluída, o valor retornado é um objeto PushNotificationChannel que contém o URI.


var channel;
var pushNotifications = Windows.Networking.PushNotifications;
var channelOperation = pushNotifications.PushNotificationChannelManager.createPushNotificationChannelForApplicationAsync();

return channelOperation.then(function (newChannel) {
    channel = newChannel;
    // Success. The channel URI is found in newChannel.uri.
    },
    function (error) {
        // Could not create a channel. Retrieve the error through error.number.
    }
);

Etapa 2: Envie o URI de canal para o seu servidor

O URI do canal é encapsulado em uma solicitação POST do HTTP e enviado ao servidor.

Importante Você deve enviar essas informações ao seu servidor de maneira segura. Você deve exigir que o aplicativo se autentique no servidor durante a transmissão do URI de canal. Criptografe as informações e use um protocolo seguro como o HTTPS.


var serverUrl = "https://www.contoso.com";

var xhr = new WinJS.xhr({
        type: "POST", 
        url: serverUrl,
        headers: {"Content-Type": "application/x-www-form-urlencoded"},
        data: "channelUri=" + channel.uri
}).then(function (req) {
        // Channel URI successfully sent to server. Retrieve the response from req.response.
    },
    function (req) {
        // Could not send channel URI to server. Retrieve the error through req.statusText.
    }
);

Comentários

Solicitando canais

Você deve solicitar um novo canal cada vez que seu aplicativo é chamado, usando a seguinte lógica:

Solicitar um canal.
Comparar o novo canal com seu canal anterior. Se o canal for o mesmo, você não precisa fazer mais nada. Observe que isso requer que seu aplicativo armazene o canal localmente cada vez que o aplicativo o enviar com sucesso para seu serviço, de forma que você terá o canal para comparar posteriormente.
Se o canal tiver sido alterado, envie o novo canal para seu serviço da Web. Inclua lógica de manipulação de erro sempre que enviar um novo canal nos seguintes casos:
- Seu aplicativo nunca enviou um canal para o serviço da Web antes.
- A última vez que seu aplicativo tentou enviar o canal para o serviço da Web, ele não foi bem-sucedido.

Chamadas diferentes para o método createPushNotificationChannelForApplicationAsync nem sempre retornam um canal diferente. Se o canal não tiver sido alterado desde a última chamada, seu aplicativo deverá conservar esforço e tráfego de Internet não reenviando o mesmo canal ao seu serviço. Um aplicativo pode ter várias URIs de canal válidas ao mesmo tempo. Como cada canal exclusivo permanece válido até expirar, não há problema em solicitar um novo canal porque ele não afetará o tempo de expiração de qualquer canal anterior.

Ao solicitar um novo canal sempre que o seu aplicativo é invocado, você maximiza suas chances de sempre ter acesso a um canal válido. Isso é particularmente importante se for vital para o seu cenário de bloco que o conteúdo sempre seja dinâmico. Se você estiver preocupado de que um usuário talvez não execute o seu aplicativo mais de uma vez a cada 30 dias, poderá implementar uma tarefa em segundo plano para executar o código de solicitação de canal regularmente.

Manipulando erros em solicitações de canal

A chamada a ao método createPushNotificationChannelForApplicationAsync poderá falhar se a Internet não estiver disponível. Para lidar com isso, adicione lógica de nova tentativa ao código da etapa 2. Recomendamos três tentativas com um atraso de 10 segundos entre cada tentativa sem êxito. Se todas as três tentativas falharem, seu aplicativo deve aguardar até a próxima vez em que o usuário o iniciar para tentar novamente.

Fechando canais

Seu aplicativo pode parar imediatamente a entrega de notificações em todos os canais chamando o método close. Embora isso não seja comum para seu aplicativo, pode haver certos cenários em que você deseja parar o envio de toda notificação para seu aplicativo. Por exemplo, se seu aplicativo tiver o conceito de contas de usuário e um usuário desconectar-se desse aplicativo, é razoável que o bloco não mostre mais as informações pessoais desse usuário. Para limpar com sucesso o bloco de conteúdo e parar a entrega de notificações, você deve fazer o seguinte:

Pare todas as atualizações de bloco chamando o método PushNotificationChannel.close em qualquer de seus canais de notificação que estejam entregando notificações de bloco, do sistema, ou brutas a um usuário. Chamar o método close assegura que mais nenhuma notificação para esse usuário possa ser entregue ao cliente.
Limpe o conteúdo chamando o método TileUpdater.clear e remova os dados do usuário do bloco.