Como manipular a ativação a partir de uma notificação do sistema (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 Como manipular ativação de uma notificação do sistema (XAML).

 

Este tópico demonstra as ações que você deve executar como resposta quando o usuário clica em uma notificação do sistema enviada de seu aplicativo. O aplicativo deve responder exibindo a interface do usuário específica à notificação do sistema. O aplicativo normalmente é iniciado em um contexto ou modo de exibição relacionado ao conteúdo da notificação do sistema. Para isso, inclua uma cadeia de caracteres de ativação na carga da notificação do sistema, que é então passada ao aplicativo como um argumento no evento de ativação. O fluxo de dados básico é mostrado aqui:

  1. O aplicativo ou serviço da Web cria e envia a carga de notificação, incluindo a cadeia de caracteres de inicialização
  2. A notificação do sistema é criada e/ou enviada à central de ações
  3. O usuário seleciona uma notificação do sistema (clique ou toque)
  4. O evento ativado dispara
  5. O manipulador do evento ativado do aplicativo lê a cadeia de caracteres de inicialização
  6. O aplicativo é ativado usando os parâmetros fornecidos na cadeia de caracteres de inicialização

Observação  Quando testar a funcionalidade do código de notificação do sistema por meio do Microsoft Visual Studio, você deve usar a configuração de depuração da Máquina Local ou Máquina Remota em uma máquina Windows x86, x64 ou Tempo de Execução do Windows. Não é possível usar a opção da função de depuração do Visual Studio Simulator—seu código compilará e executará no Simulador, mas a notificação do sistema não aparecerá.

 

O que você precisa saber

Tecnologias

  • Windows Runtime

Pré-requisitos

Para compreender este tópico, você precisa de:

Instruções

Etapa 1: Incluir dados de ativação na carga da notificação do sistema

Quando seu aplicativo é ativado por uma notificação do sistema, ele tem que receber informações relacionadas ao conteúdo da notificação do sistema. A partir disso, ele reflete o conteúdo iniciando-o em um modo de exibição associado em vez do padrão. Quando o aplicativo ou serviço Web cria a notificação do sistema, ele usa o atributo launch para especificar as informações de ativação. Pense na cadeia de caracteres como um equivalente aos argumentos de linha de comando. A cadeia de caracteres pode incluir qualquer informação que o aplicativo consiga reconhecer, se isso não tornar inválida a carga XML. Observe que o tamanho total da carga XML da notificação do sistema, incluindo a cadeia de caracteres de inicialização, não pode passar de 5 KB.

Se você não incluir uma cadeia de caracteres de atributo de inicialização, o aplicativo será iniciado normalmente, como se o usuário o tivesse iniciado a partir da tela inicial.

Nesta etapa, nós consideramos que um objeto XmlDocument chamado toastXml já tenha sido criado. Este exemplo cria o atributo launch, atribui seu valor de cadeia de caracteres e adiciona-o à carga XML da notificação do sistema. As instruções sobre como criar a notificação do sistema completa estão em Guia de início rápido: enviando uma notificação do sistema.


var launchAttribute = toastXml.createAttribute("launch");
launchAttribute.value = "{\"myContext\":\"12345\"}";
var toastNode = toastXml.selectSingleNode("/toast");
toastNode.attributes.setNamedItem(launchAttribute);

O código acima resulta no seguinte XML, baseado no conteúdo do elemento visual definido no Guia de início rápido: enviando uma notificação do sistema.


<toast launch="{&quot;myContext&quot;:&quot;12345&quot;}">
    <visual>
        <binding template="ToastImageAndText01">
            <image id="1" src="ms-appx:///images/redWide.png" alt="red graphic"/>
            <text id="1">Hello World!</text>
        </binding>
    </visual>
</toast>

Etapa 2: Registrar-se para o evento "ativado"

Quando o usuário clica em sua notificação do sistema ou a seleciona por toque, o evento activated é acionado. O aplicativo deve se registrar usando a função addEventListener para ser informado sobre o evento.

Observação  Se você não incluir uma cadeia de caracteres de atributo de inicialização em sua notificação do sistema e o seu aplicativo já estiver em execução quando a notificação do sistema for selecionada, o evento activated não será acionado.

 

WinJS.Application.addEventListener("activated", onActivatedHandler, false);

Etapa 3: Implementar um manipulador para o seu evento "ativado" da notificação do sistema

O manipulador de eventos registrado recebe todos os eventos de ativação, independentemente do tipo de ativação. A propriedade kind incluída na notificação do evento indica o tipo de evento de ativação. Quando o usuário clica em uma notificação do sistema que tenha o atributo launch especificado em sua carga XML, um evento de ativação do tipo launch é acionado. Este é o mesmo evento que é acionado quando o usuário toca no bloco principal ou secundário de um aplicativo.

A cadeia de caracteres de ativação especificada através do atributo launch na etapa 1 é incluída na propriedade arguments da notificação do evento.

Este exemplo mostra a descrição do manipulador de eventos ativado registrado na etapa 2.


function onActivatedHandler(args) {
    if (args.detail.kind === Windows.ApplicationModel.Activation.ActivationKind.launch) {
        var launchString = args.detail.arguments;

        // Handle activation as required for your app, using the launch string.
    }
}

Tópicos relacionados

Exemplo de notificações do sistema

Windows.UI.Notifications API namespace

Visão geral das notificações do sistema

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

Guia de início rápido: enviando uma notificação do sistema

O catálogo de modelos de notificação do sistema

Esquema XML de notificação do sistema