Guia de início rápido: criando e registrando uma tarefa em segundo plano de notificação bruta (HTML)

  • Artigo

[ 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 Guia de início rápido: criando e registrando uma tarefa em segundo plano de notificação bruta (XAML).

 

Você pode criar e registrar uma função de tarefa em segundo plano para o seu aplicativo da Windows Store. Esse código é executado em resposta ao recebimento de uma notificação bruta, que confere funcionalidade ao seu aplicativo quando ele não está em primeiro plano.

Para concluir esse procedimento, você deve editar três arquivos separados: o código do aplicativo, o manifesto do aplicativo e um novo arquivo JavaScript que contenha o código da tarefa em segundo plano.

Pré-requisitos

Para compreender este tópico ou para usar o código que ele oferece, você precisará de:

Instruções

1. Criar a classe da tarefa em segundo plano

Crie um novo arquivo JavaScript (.js) em seu projeto. Neste caso, chamaremos o arquivo de examplebackgroundtask.js. O código desse arquivo será acionado para execução em segundo plano quando receber uma notificação bruta. Adicione o esqueleto da função JavaScript (mostrado a seguir) ao arquivo.

A função doWork deste exemplo (é claro que você pode chamá-la do que quiser) contém o código que compõe a tarefa em segundo plano real. Primeiro, ela recupera o conteúdo da notificação por meio da classe Windows.UI.WebUI.WebUIBackgroundTaskInstance, usada para obter informações sobre a instância atual da tarefa em segundo plano. O corpo do código, específico ao conteúdo da notificação bruta definida pelo aplicativo, substituirá o comentário "// ...".

Importante  Observe que o código da tarefa termina chamando a função close interna do JavaScript. Esse método deve ser chamado sempre que uma tarefa em segundo plano do JavaScript conclui seu trabalho ou é cancelada. Se a tarefa em segundo plano não fechar sozinha, o processo da tarefa em segundo plano poderá continuar existindo, consumindo memória e bateria, mesmo que a tarefa em segundo plano tenha sido concluída.

 


(function () {
    "use strict";

    var backgroundTaskInstance = Windows.UI.WebUI.WebUIBackgroundTaskInstance.current;

    function doWork() {
        var notificationContent = backgroundTaskInstance.triggerDetails.content; 

        // ...

        close();
    }

    doWork();
})();

2. Declare a tarefa em segundo plano no manifesto do aplicativo.

Observação  Como pré-requisito para esta etapa, o aplicativo deve selecionar uma opção de tela de bloqueio e fornecer um logotipo de notificação antes de oferecer suporte a tarefas em segundo plano. Para saber mais, veja Guia de início rápido: mostrando as atualizações de bloco e notificação na tela de bloqueio.

 

Para o aplicativo registrar uma tarefa em segundo plano, você deve declarar a tarefa em segundo plano e seu gatilho no manifesto do aplicativo. Isso pode ser feito diretamente como XML ou pelo Editor de Manifesto do Microsoft Visual Studio.

  • Para usar o Editor de Manifesto, clique duas vezes no arquivo Package.appxmanifest do projeto no Visual Studio. Na guia Declarações, selecione Tarefas em Segundo Plano na lista suspensa Declarações Disponíveis. Como gatilho, selecione Notificação por push em Propriedades. Na caixa Página inicial, insira o nome do arquivo .js da tarefa em segundo plano (no nosso caso, examplebackgroundtask.js).

    Se seu aplicativo usa mais de uma tarefa em segundo plano, repita esta etapa para cada tarefa, apontando cada vez para um arquivo diferente.

  • Para adicionar as informações diretamente ao XML do manifesto, abra o manifesto em um editor de texto. No elemento Extensions, adicione um elemento Extension para a classe de tarefa em segundo plano. O atributo Category deve ser definido como "windows.backgroundTasks" e o atributo StartPage deve nomear o arquivo .js da tarefa em segundo plano (em nosso caso, examplebackgroundtask.js).

    Se seu aplicativo usa mais de uma tarefa em segundo plano, adicione um elemento Extension separado a cada tarefa, cada elemento apontando para um arquivo .js diferente.

    Você deve listar cada tipo de gatilho que uma tarefa em segundo plano usa. Como estamos criando uma tarefa em segundo plano que aciona uma resposta a uma notificação bruta, declararemos um gatilho de notificação por push. Adicione um elemento BackgroundTasks ao elemento Extension, com seu elemento Task definido como "pushNotification".

    O elemento Extension completo é mostrado aqui.


<Extension Category="windows.backgroundTasks" StartPage="js\examplebackgroundtask.js">
  <BackgroundTasks>
    <Task Type="pushNotification"/>
  </BackgroundTasks>
</Extension>

3. Registre a tarefa em segundo plano no aplicativo.

Os exemplos a seguir fornecem código que você adiciona ao seu aplicativo (por exemplo, no arquivo Default.js) para registrar a tarefa em segundo plano como resposta a uma notificação bruta.

Primeiro, determine se a tarefa em segundo plano já está registrada. Esta etapa é importante. Se o seu aplicativo não verificar se já existe um registro de tarefa em segundo plano, ele poderá registrar a mesma tarefa mais de uma vez. Isso pode causar problemas de desempenho e de uso da CPU que impeçam a conclusão da tarefa.

O seguinte exemplo itera por meio da propriedade Windows.ApplicationModel.Background.BackgroundTaskRegistration.AllTasks e define um sinalizador como true quando a tarefa já está registrada:


var taskRegistered = false;
var exampleTaskName = "Example background task class name";

var background = Windows.ApplicationModel.Background;
var iter = background.BackgroundTaskRegistration.AllTasks.first();

while (iter.hasCurrent) {
    var task = iter.current.value;
    
    if (task.name === exampleTaskName) {
        taskRegistered = true;
        break;
    }

    iter.moveNext();
}

Se o aplicativo detectar que a tarefa em segundo plano não está registrada, ele poderá registrá-la chamando o método Windows.ApplicationModel.Background.BackgroundTaskBuilder.register. Na chamada a esse método, você incluirá o nome do arquivo .js da tarefa em segundo plano (em nosso caso, examplebackgroundtask.js) e um objeto PushNotificationTrigger.


if (taskRegistered != true) {
    var builder = new Windows.ApplicationModel.Background.BackgroundTaskBuilder();
    var trigger = new Windows.ApplicationModel.Background.PushNotificationTrigger();

    builder.name = exampleTaskName;
    builder.taskEntryPoint = "js\\ExampleBackgroundTask.js";
    builder.setTrigger(trigger);

    var task = builder.register();
}

Resumo

Agora você já conhece os conceitos básicos sobre como criar uma classe de tarefa em segundo plano para usar com notificações brutas, incluindo como registrar a tarefa em segundo plano a partir do aplicativo. Você também deve entender como atualizar o manifesto do aplicativo, de modo que o Windows permita que o seu aplicativo registre as tarefas em segundo plano.

Observação  Você pode baixar a amostra de tarefa em segundo plano para ver esses exemplos de código e muito mais, no contexto de um aplicativo JavaScript completo e robusto que usa vários tipos diferentes de tarefas em segundo plano.

 

Tópicos relacionados

Exemplo de notificações brutas

Visão geral de notificações brutas

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

Guia de início rápido: interceptando notificações por push para aplicativos em execução

RawNotification