Como usar o WNS para fornecer notificações por push brutas a um aplicativo da tela de bloqueio (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]

Este tópico mostrará como usar o WNS (Serviço de Notificação do Windows) e notificações brutas por push para receber notificações de rede no segundo plano em um aplicativo do Tempo de Execução do Windows na tela de bloqueio. Este tópico fornece orientação para o processo de registrar um canal de notificações por push e enviá-lo ao servidor, registrar uma tarefa em segundo plano para ativar uma notificação bruta por push e enviar uma notificação bruta por push ao canal e ativar essa tarefa em segundo plano.

O que você precisa saber

Tecnologias

Windows.Networking.PushNotifications

Habilita comunicações de rede em segundo plano usando notificações brutas por push.

Pré-requisitos

As informações a seguir se aplicam a qualquer aplicativo do Tempo de Execução do Windows conectado ou com reconhecimento de rede que depende de conexões de rede usando notificações brutas por push para se manter sempre conectado. Este tópico se aplica a aplicativos escritos em JavaScript no Windows 8.1, no Windows Phone 8.1 e no Windows Server 2012 R2.

A conectividade de rede em segundo plano usando notificações por push não processadas tem suporte em aplicativos JavaScript e em aplicativos escritos em C++/XAML, bem como em aplicativos que usam o .NET Framework 4.5 em C#, VB.NET ou C++ gerenciada. Para saber mais sobre tarefas de rede em segundo plano que se aplicam a aplicativos em JavaScript, veja Dando suporte ao seu aplicativo com tarefas em segundo plano.

Instruções

Usando o WNS para enviar notificações por push brutas a um aplicativo da tela de bloqueio

Os aplicativos que usam o WNS não precisam estar em execução para receber notificações por push. Além disso, eles podem dar ao usuário a impressão de que são executados quando não estão em execução. Por exemplo, um aplicativo de previsões do tempo pode sempre mostrar a previsão mais recente em um live tile atualizado. O WNS também pode ser usado para exibir notificações aos usuários na tela quando ocorrem eventos importantes. Um bom exemplo de notificação na tela é uma notícia de última hora. Qualquer dispositivo executando Windows 8.1, Windows Phone 8.1 ou Windows Server 2012 R2 com uma conexão com a Internet pode usar WNS. Normalmente, essas notificações do WNS são entregues assim que são enviadas.

Embora o WNS ajude a melhorar o desempenho dos blocos e das notificações na tela inicial do Windows 8.1, ele também poe ser usado para possibilitar cenários de conectividade em tempo real, como mensagens instantâneas, VoIP e e-mail. Quando um aplicativo que usa WNS é adicionado à tela de bloqueio, ele pode ser usado para ativar uma tarefa em segundo plano. Uma tarefa em segundo plano é a parte do código do aplicativo executada quando o aplicativo está em segundo plano (e não mais em primeiro plano).

Veja alguns exemplos de tarefas em segundo plano que podem ser ativadas por uma notificação do WNS:

Chamar a API de notificação de notificações para ampliar um ícone de notificação de um aplicativo de e-mail na tela de bloqueio a fim de indicar o recebimento de uma nova mensagem de e-mail.
Chamar a API de notificação do sistema de modificação para emitir uma notificação para um aplicativo de VoIP indicando o recebimento de uma chamada telefônica para o usuário.

Há quatro tipos de notificações por push:

Atualização de bloco
Atualização de notificação
Notificação do sistema
Notificação não processada

Todos os aplicativos do Tempo de Execução do Windows podem usar as três primeiras notificações por push quando estão em primeiro plano. Apenas os aplicativos da tela de bloqueio podem receber notificações brutas por push do WNS. As notificações brutas permitem que os aplicativos da tela de bloqueio executem códigos na forma de uma tarefa em segundo plano quando a notificação por push não processada chega do servidor do WNS, mesmo quando o aplicativo não está em primeiro plano.

A maioria dos aplicativos não precisa ser um aplicativo da tela de bloqueio e pode usar o WNS sem estar nessa tela. O WNS pode ser usado por todos os aplicativos para atualizar blocos e notificações, bem como para emitir notificações do sistema quando o aplicativo está em primeiro plano. Usar o WNS com um aplicativo da tela de bloqueio é mais avançado do que usar o WNS para destacar blocos e emitir notificações aos usuários. Os desenvolvedores devem se familiarizar com a documentação do WNS no MSDN antes de tentar usar o WNS com uma tela de bloqueio. Para saber mais, veja a visão geral de notificações por push.

Você precisará de uma chave secreta, provisionada pela Windows Store, para enviar notificações por push ao WNS. Para saber mais sobre autenticação com o WNS e configuração de seu aplicativo, veja o tópico sobre como autenticar com o WNS (Serviço de Notificação por Push) do Windows.

As etapas a seguir mostram como enviar uma notificação por push não processada para um aplicativo da tela de bloqueio.

Registre-se em um canal de notificação por push do WNS e envie-o ao servidor.
Envie uma notificação por push não processada formatada corretamente ao WNS usando o canal de notificação.
Escreva uma tarefa em tela de fundo que seja ativada a partir de uma notificação por push bruta.

As notificações brutas por push são enviadas a um aplicativo cliente usando um servidor de aplicativos do desenvolvedor por meio de um PUSH HTTP de uma carga XML bem constituída para um canal de notificação Um canal de notificação é gerado pelo aplicativo cliente, enviado ao servidor de aplicativos e usado para enviar a notificação por push. O canal de notificação é exclusivo para a instância de seu aplicativo na conta do usuário no Windows 8.1.

JJ679947.wedge(pt-br,WIN.10).gif Registre-se em um canal de notificação por push e envie-o ao servidor.

Registre-se em um canal chamando um dos métodos CreatePushNotificationChannelForApplicationAsync na classe PushNotificationChannelManager, no namespace Windows.Networking.PushNotifications.

Essa ação gerará um canal de notificação por push para o aplicativo, que será parecido com o seguinte:
```
https://db3.notify.windows.com/?token=AQQAAADX3Wr8MA%2fCoZk4n1CmR5ZU7tdic6ksvG4TQq1tiyZtpetjfzuPHSjvliEeqaqJcPuo1jrVnbyCZvnbuU%2byLvZNDONTgUNu6lavpl5EGtWx7iQgpGkyHLbZeosxioQ42Cg%3d
```
Envie o canal ao servidor Os canais expiram após 30 dias. Por isso, há algumas práticas recomendadas:
- Registre-se para obter um novo canal de notificação por push sempre que o aplicativo é iniciado e envie-o ao servidor para substituir o canal anteriormente vinculado ao usuário.
- Para um computador local que permanece ligado, execute uma tarefa em segundo plano para renovar o canal de vez em quando antes que ele expire. Isso é conhecido como temporizador de manutenção.

JJ679947.wedge(pt-br,WIN.10).gif Registre uma tarefa em segundo plano que seja ativada a partir de uma notificação por push não processada

Para criar uma tarefa em segundo plano executada sempre que uma notificação por push não processada é recebida, você deve especificar o arquivo de origem JavaScript que contém o código que deve ser ativado pela tarefa em segundo plano. Para isso, você deve garantir que o manifesto do aplicativo aponte para o arquivo de origem da tarefa em segundo plano. O manifesto do aplicativo deve conter o nome do arquivo de origem JavaScript da tarefa em segundo plano.

A amostra a seguir adiciona extensões para uma tarefa em segundo plano PushNotifyTask sob o elemento <Application> em um manifesto de aplicativo.
```
  <Extensions>
    <Extension Category="windows.backgroundTasks" StartPage="js\backgroundTask.js">
      <BackgroundTasks>
        <Task Type="pushNotification" />
      </BackgroundTasks>
    </Extension>
  </Extensions>
```

O aplicativo precisa abrir o canal para notificações brutas por push.

A amostra a seguir mostra como abrir um canal para uma notificação por push não processada.


    // Open the channel. See the "Push and Polling Notifications" sample for more detail
    function openNotificationsChannel() {
        var channelOperation = pushNotifications.PushNotificationChannelManager.createPushNotificationChannelForApplicationAsync();
        WinJS.log && WinJS.log("Opening a channel...", "sample", "status");
        return channelOperation.then(function (newChannel) {
            WinJS.log && WinJS.log("Channel request succeeded!", "sample", "status");
            document.getElementById("scenario1ChannelOutput").value = newChannel.uri;
            SdkSample.channel = newChannel;
        },
            function (error) {
                WinJS.log && WinJS.log("Could not create a channel (error number: " + error.number + ")", "sample", "error");
            }
        );
    }

O aplicativo também deve registrar a tarefa em segundo plano para que ela seja ativada quando uma notificação por push não processada for recebida.

A amostra a seguir mostra como registrar uma tarefa em segundo plano para notificações por push não processada.

    // Register the background task for raw notifications
    //
    function registerBackgroundTask() {
        var taskBuilder = new background.BackgroundTaskBuilder();
        var trigger = new background.PushNotificationTrigger();
        taskBuilder.setTrigger(trigger);
        taskBuilder.taskEntryPoint = sampleTaskEntryPoint;
        taskBuilder.name = sampleTaskName;

        try {
            var task = taskBuilder.register();
            task.addEventListener("completed", backgroundTaskComplete);
            WinJS.log && WinJS.log("Background task registered", "sample", "status");
        } catch (e) {
            WinJS.log && WinJS.log("Registration error: " + e.message, "sample", "error");
            unregisterBackgroundTask();
        }
    }

    function unregisterBackgroundTask() {
        var iter = background.BackgroundTaskRegistration.allTasks.first();
        while (iter.hasCurrent) {
            var task = iter.current.value;
            if (task.name === sampleTaskName) {
                task.unregister(true);
                return true;
            }
            iter.moveNext();
        }
        return false;
    }

Você também precisa fornecer códigos para a função executada quando a tarefa em segundo plano é disparada.

Para saber mais sobre como escrever uma tarefa em segundo plano de forma a receber notificações de rede em segundo plano que usam notificações brutas por push, veja Como escrever uma tarefa em segundo plano para notificações brutas por push.

Observação

Você não pode referenciar elementos da interface do usuário de seu aplicativo em uma tarefa em segundo plano, pois os elementos da interface do aplicativo não estão em execução. Isso significa que os retornos de chamada do transporte de rede não devem ter afinidade com o STA (Single Thread Apartment) da interface do usuário. Qualquer objeto que tenha afinidade com o STA da interface do usuário (também chamado de STA do aplicativo) não pode ser acessado por taregas em segundo plano.

Quando seu código está em execução na tarefa em segundo plano, você pode configurar o aplicativo para ativação, sincronizar o estado entre o cliente e o servidor e emitir uma notificação ao usuário.

As notificações brutas por push são semelhantes a notificações e notificações de bloco. A principal diferença é que a carga de uma notificação por push não processada não contém atributos que atualizam partes da interface do usuário do Windows 8.1. A carga de trabalho da notificação por push não processada é completamente formada por dados contextuais que são transferidos diretamente para o aplicativo quando a tarefa em segundo plano é ativada. Seu aplicativo deve compreender o formato dos dados de contexto enviados pelo servidor.

Antes de o servidor enviar uma notificação por push não processada, você deve fazer o seguinte:

JJ679947.wedge(pt-br,WIN.10).gif Enviar uma notificação por push não processada ao canal e ativar a tarefa em segundo plano

Certifique-se de ter registrado seu aplicativo na Windows Store e de ter um SID de pacote e chave privada.
Crie um código no servidor do aplicativo para realizar autenticação no WNS usando o SID de pacote e chave privada antes de enviar uma notificação por push do servidor.
Crie uma notificação bruta por push do WNS adequada e envie uma solicitação HTTP POST ao canal de notificação anteriormente recebido do aplicativo do Tempo de Execução do Windows. A solicitação HTTP POST deve incluir vários cabeçalhos HTTP adicionais:
- X-WNS-Type=wns/raw
- Content-Type=application/octet-stream
- Authorization=a cadeia “Bearer”, um espaço e o token de autorização recebido da etapa de autenticação
O corpo do POST HTTP deve incluir todo o contexto que você quer fornecer ao aplicativo cliente quando ele executa a tarefa em segundo plano disparada pelo recebimento da notificação por push não processada. A quantidade máxima de dados que pode ser incluída na carga da notificação bruta é 5 KB.

Quando a notificação é recebida pelo cliente, a tarefa em segundo plano é ativada e a carga de dados especificada é transferida e fica acessível por meio do código de tarefa em segundo plano do aplicativo.

Etapas anteriores

Para saber mais sobre como criar um aplicativo de tela de bloqueio de forma a receber notificações de rede em segundo plano que usam notificações brutas por push, veja Guia de início rápido: criar um aplicativo de tela de bloqueio que usa notificações brutas por push em segundo plano.

Etapas adicionais

Para saber mais sobre como escrever uma tarefa em segundo plano de forma a receber notificações de rede em segundo plano que usam notificações brutas por push, veja Como escrever uma tarefa em segundo plano para notificações brutas por push.

Para saber mais sobre as orientações e listas de verificação para o uso de notificações por push não processadas, veja

Diretrizes e lista de verificação para notificações não processadas