Notificações de blocos rastreáveis

  • Artigo

As notificações de blocos perseguíveis permitem determinar quais notificações de blocos o Live Tile do seu aplicativo estava exibindo quando o usuário clicou no bloco.
Por exemplo, um aplicativo de notícias poderia utilizar esse recurso para determinar qual notícia seu Bloco Dinâmico estava exibindo quando o usuário o iniciou; Isso pode garantir que a história seja exibida com destaque para que o usuário possa encontrá-la.

Importante

Requer Atualização de Aniversário: para utilizar notificações de bloco rastreáveis com aplicativos UWP baseados em C#, C++ ou VB, você deve ter como destino o SDK 14393 e estar executando a compilação 14393 ou posterior. Para aplicativos UWP baseados em JavaScript, você deve ter como destino o SDK 17134 e estar executando o build 17134 ou posterior.

APIs importantes: propriedade LaunchActivatedEventArgs.TileActivatedInfo, classe TileActivatedInfo

Como ele funciona

Para habilitar notificações de bloco localizáveis, use a propriedade Arguments na carga de notificação de bloco, semelhante à propriedade de inicialização na carga de notificação do sistema, para incorporar informações sobre o conteúdo na notificação de bloco.

Quando seu aplicativo é iniciado por meio do Bloco Dinâmico, o sistema retorna uma lista de argumentos das notificações de bloco atuais/exibidas recentemente.

Quando usar notificações de blocos perseguíveis

Notificações de blocos rastreáveis geralmente são usadas quando você está usando a fila de notificações no Bloco Dinâmico (o que significa que você está percorrendo até 5 notificações diferentes). Elas também são benéficas quando o conteúdo do Bloco Dinâmico está potencialmente fora de sincronia com o conteúdo mais recente do aplicativo. Por exemplo, o aplicativo de notícias atualiza seu Bloco Dinâmico a cada 30 minutos, mas quando o aplicativo é iniciado, ele carrega as notícias mais recentes (que podem não incluir algo que estava no bloco do último intervalo de sondagem). Quando isso acontece, o usuário pode ficar frustrado por não conseguir encontrar a história que viu em seu Bloco Dinâmico. É aí que as notificações de bloco rastreáveis podem ajudar, permitindo que você verifique se o que o usuário viu em seu Bloco é facilmente detectável.

O que fazer com notificações de bloco rastreáveis

A coisa mais importante a observar é que, na maioria dos cenários, você NÃO deve navegar diretamente para a notificação específica que estava no bloco quando o usuário clicou nele. Seu Bloco Dinâmico é usado como um ponto de entrada para o aplicativo. Pode haver dois cenários quando um usuário clica no Bloco Dinâmico: (1) ele queria iniciar seu aplicativo normalmente ou (2) queria ver mais informações sobre uma notificação específica que estava no Bloco Dinâmico. Como não há como o usuário dizer explicitamente qual é comportamento desejado, a experiência ideal é iniciar seu aplicativo normalmente, garantindo que a notificação que o usuário viu seja facilmente detectável.

Por exemplo, clicar no Bloco Dinâmico do aplicativo MSN News inicia o aplicativo normalmente: ele exibe a página inicial ou qualquer artigo que o usuário estava lendo anteriormente. No entanto, na página inicial, o aplicativo garante que a história do Bloco Dinâmico seja facilmente detectável. Dessa forma, há suporte para ambos os cenários: o cenário em que você simplesmente deseja iniciar/retomar o aplicativo e o cenário em que deseja exibir a história específica.

Como incluir a propriedade Arguments na carga de notificação de bloco

Em uma carga de notificação, a propriedade Arguments permite que seu aplicativo forneça dados que você pode utilizar para identificar a notificação posteriormente. Por exemplo, seus argumentos podem incluir o ID da matéria, para que, quando iniciado, você possa recuperar e exibir a história. A propriedade aceita uma cadeia de caracteres, que pode ser serializada como você quiser (cadeia de caracteres de consulta, JSON, etc), mas normalmente recomendamos o formato de cadeia de caracteres de consulta, já que é leve e codifica XML muito bem.

A propriedade pode ser definida nos elementos TileVisual e TileBinding e será reduzida em cascata. Se quiser os mesmos argumentos em todos os tamanhos de blocos, basta defini-los argumentos em TileVisual. Se precisar de argumentos específicos para tamanhos de bloco específicos, poderá definir os argumentos em elementos TileBinding individuais.

Este exemplo cria uma carga de notificação que usa a propriedade Arguments, de forma que a notificação possa ser identificada posteriormente.

// Uses the following NuGet packages
// - Microsoft.Toolkit.Uwp.Notifications
// - QueryString.NET
 
TileContent content = new TileContent()
{
    Visual = new TileVisual()
    {
        // These arguments cascade down to Medium and Wide
        Arguments = new QueryString()
        {
            { "action", "storyClicked" },
            { "story", "201c9b1" }
        }.ToString(),
 
 
        // Medium tile
        TileMedium = new TileBinding()
        {
            Content = new TileBindingContentAdaptive()
            {
                // Omitted
            }
        },
 
 
        // Wide tile is same as Medium
        TileWide = new TileBinding() { /* Omitted */ },
 
 
        // Large tile is an aggregate of multiple stories
        // and therefore needs different arguments
        TileLarge = new TileBinding()
        {
            Arguments = new QueryString()
            {
                { "action", "storiesClicked" },
                { "story", "43f939ag" },
                { "story", "201c9b1" },
                { "story", "d9481ca" }
            }.ToString(),
 
            Content = new TileBindingContentAdaptive() { /* Omitted */ }
        }
    }
};

Como verificar a propriedade Arguments quando seu aplicativo é iniciado

A maioria dos aplicativos tem um arquivo App.xaml.cs que contém uma substituição para o método OnLaunched. Como o próprio nome sugere, seu aplicativo chama esse método ao ser iniciado. É necessário um único argumento, um objeto LaunchActivatedEventArgs.

O objeto LaunchActivatedEventArgs tem uma propriedade que permite notificações rastreáveis: a propriedade TileActivatedInfo, que fornece acesso a um objeto TileActivatedInfo. Quando o usuário inicia seu aplicativo a partir do seu bloco (em vez de na lista de aplicativos, pesquisa ou qualquer outro ponto de entrada), o aplicativo inicializa essa propriedade.

O objeto TileActivatedInfo contém uma propriedade chamada RecentlyShownNotifications, que contém uma lista de notificações que foram mostradas no bloco nos últimos 15 minutos. O primeiro item da lista representa a notificação atualmente no bloco e os itens subsequentes representam as notificações que o usuário viu antes da atual. Se o bloco tiver sido limpo, essa lista estará vazia.

Cada ShownTileNotification tem uma propriedade Arguments. A propriedade Arguments será inicializada com a cadeia de caracteres Arguments da carga de notificação de bloco ou será nula se a carga não incluir a cadeia de caracteres Arguments.

protected override void OnLaunched(LaunchActivatedEventArgs args)
{
    // If the API is present (doesn't exist on 10240 and 10586)
    if (ApiInformation.IsPropertyPresent(typeof(LaunchActivatedEventArgs).FullName, nameof(LaunchActivatedEventArgs.TileActivatedInfo)))
    {
        // If clicked on from tile
        if (args.TileActivatedInfo != null)
        {
            // If tile notification(s) were present
            if (args.TileActivatedInfo.RecentlyShownNotifications.Count > 0)
            {
                // Get arguments from the notifications that were recently displayed
                string[] allArgs = args.TileActivatedInfo.RecentlyShownNotifications
                .Select(i => i.Arguments)
                .ToArray();
 
                // TODO: Highlight each story in the app
            }
        }
    }
 
    // TODO: Initialize app
}

Acessando OnLaunched a partir de aplicativos para desktop

Aplicativos para desktop (como WPF, etc) usando a Ponte de Desktop, podem utilizar blocos rastreáveis também! A única diferença é o acesso aos argumentos OnLaunched. Observe que primeiro você deve empacotar seu aplicativo com a Ponte de Desktop.

Importante

Requer atualização de outubro de 2018: para usar a API AppInstance.GetActivatedEventArgs(), você deve ter como alvo o SDK 17763 e estar executando a compilação 17763 ou posterior.

Em aplicativos para desktop, para acessar os argumentos de inicialização, faça o seguinte...


static void Main()
{
    Application.EnableVisualStyles();
    Application.SetCompatibleTextRenderingDefault(false);

    // API only available on build 17763 or later
    var args = AppInstance.GetActivatedEventArgs();
    switch (args.Kind)
    {
        case ActivationKind.Launch:

            var launchArgs = args as LaunchActivatedEventArgs;

            // If clicked on from tile
            if (launchArgs.TileActivatedInfo != null)
            {
                // If tile notification(s) were present
                if (launchArgs.TileActivatedInfo.RecentlyShownNotifications.Count > 0)
                {
                    // Get arguments from the notifications that were recently displayed
                    string[] allTileArgs = launchArgs.TileActivatedInfo.RecentlyShownNotifications
                    .Select(i => i.Arguments)
                    .ToArray();
     
                    // TODO: Highlight each story in the app
                }
            }
    
            break;

Exemplo de XML bruto

Se estiver usando XML bruto em vez da biblioteca de notificações, este é o XML.

<tile>
  <visual arguments="action=storyClicked&amp;story=201c9b1">
 
    <binding template="TileMedium">
       
      <text>Kitten learns how to drive a car...</text>
      ... (omitted)
     
    </binding>
 
    <binding template="TileWide">
      ... (same as Medium)
    </binding>
     
    <!--Large tile is an aggregate of multiple stories-->
    <binding
      template="TileLarge"
      arguments="action=storiesClicked&amp;story=43f939ag&amp;story=201c9b1&amp;story=d9481ca">
   
      <text>Can your dog understand what you're saying?</text>
      ... (another story)
      ... (one more story)
   
    </binding>
 
  </visual>
</tile>