Guia de início rápido: Enviando uma atualização de bloco
Idioma: HTML | XAML

Início rápido: enviando uma atualização de bloco (XAML)

[ 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 C#/VB/C++? Consulte Início rápido: enviando uma atualização de bloco (HTML).
 

O bloco começa como um bloco padrão, definido no manifesto e exibido quando o seu aplicativo é instalado pela primeira vez. Após a instalação do aplicativo, você pode mudar o conteúdo do bloco através de notificações.Este Guia de início rápido orienta você ao longo das etapas para definir um novo conteúdo de bloco, enviar esse conteúdo ao bloco e removê-lo quando ele não for mais necessário. Estas ações são demonstradas por meio de uma notificação local, que é a notificação mais simples para implementação. Discutiremos as seguintes etapas:

  • Especificando um modelo para a sua notificação
  • Recuperando o conteúdo XML em branco do modelo
  • Adicionando texto à notificação
  • Adicionando uma imagem à notificação
  • Empacotando diferentes versões de notificação para diferentes tamanhos de bloco em uma única carga
  • Definindo um tempo de expiração para a sua notificação
  • Enviando a atualização para o bloco como uma notificação local

Veja este recurso em ação como parte da nossa série sobre recursos para aplicativos, do início ao fim:  Interface do usuário de aplicativo da Windows Store, do início ao fim

Observação  Neste Guia de início rápido, você vai manipular o conteúdo de notificações diretamente pelo DOM (Document Object Model) XML. Uma abordagem opcional está disponível por meio da biblioteca NotificationsExtensions, que apresenta o conteúdo XML como propriedades de objetos, incluindo o Intellisense. Para saber mais, veja Guia de início rápido: usando a biblioteca NotificationsExtensions em seu código. Para ver o código expresso com o uso de NotificationsExtensions neste Guia de início rápido, veja a Amostra de blocos e notificações de aplicativo.
 

Pré-requisitos

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

Instruções

1. Adicionar declarações de namespace

Windows.UI.Notifications inclui as APIs de bloco.



using Windows.UI.Notifications;
using Windows.Data.Xml.Dom;

2. Escolher um modelo para o bloco e recuperar seu conteúdo XML

Escolha um modelo no catálogo de modelos fornecido pelo sistema adequado às necessidades de layout do seu conteúdo. Para ver a lista completa de modelos, confira a enumeração TileTemplateType. Observe que cada notificação separada que você envia pode usar um modelo diferente.

Este exemplo usa o modelo TileWide310x150ImageAndText01, que precisa de uma imagem e uma cadeia de caracteres de texto. Um exemplo é mostrado aqui:

TileWide310x150ImageAndText01

Observação  Quando o getTemplateContent é chamado em um sistema Windows 8, ele retorna uma versão do modelo 1. Quando esse método é chamado em um sistema Windows 8.1, ele retorna uma versão do modelo 2 ou uma versão do modelo 3 para modelos só de Windows Phone. Se um aplicativo especifica a compatibilidade do Windows 8 em seu manifesto, esse método retorna uma versão do modelo 1, independentemente da versão do Windows. Neste tópico, nós vamos usar a versão do modelo 2.
 


XmlDocument tileXml = TileUpdateManager.GetTemplateContent(TileTemplateType.TileWide310x150ImageAndText01);

O método GetTemplateContent recupera um XmlDocument. O código acima recupera o esqueleto XML a seguir, cujos detalhes você especificará nas etapas subsequentes usando as funções DOM padrão:



<tile>
    <visual version="2">
        <binding template="TileWide310x150ImageAndText01" fallback="TileWideImageAndText01">
            <image id="1" src=""/>
            <text id="1"></text>
        </binding>
    </visual>
</tile>

3. Fornecer conteúdo de texto para a sua notificação

Este código recupera primeiro todos os elementos no modelo com um nome de marca "text". O modelo TileWide310x150ImageAndText01 contém apenas uma cadeia de texto, que o código atribui em seguida. Essa cadeia de caracteres pode ser quebrada, no máximo, em duas linhas; portanto, o comprimento da cadeia deve ser definido de acordo para evitar truncamentos.


   
XmlNodeList tileTextAttributes = tileXml.GetElementsByTagName("text");
tileTextAttributes[0].InnerText = "Hello World! My very own tile notification";

4. Fornecer uma imagem para a sua notificação

Este código recupera primeiro todos os elementos no modelo com um nome de marca "image". O modelo TileWide310x150ImageAndText01 inclui uma única imagem. Observe que nem todos os modelos de bloco contêm imagens; alguns deles são somente texto.

Importante  A imagem "redWide.png" utilizada aqui é apenas um exemplo e não está incluída em um projeto do Microsoft Visual Studio. Você terá que substituir "redWide.png" pelo nome de uma imagem real própria adicionada por você ao projeto antes de tentar enviar esta notificação. Se você não fizer isso, a notificação não será entregue.
 

XmlNodeList tileImageAttributes = tileXml.GetElementsByTagName("image");

Imagens podem ser usadas a partir do pacote do aplicativo, do armazenamento local do aplicativo ou da Web. Versões desta etapa são mostradas para cada fonte de imagem. Em uma notificação de bloco que contém várias imagens, os elementos de imagem podem usar qualquer combinação desses tipos de fonte de imagem. As imagens usadas em modelos devem ter menos de 200 KB de tamanho e serem menor que 1024 x 1024 pixels. Para saber mais, veja Tamanhos de imagens de bloco e notificação do sistema.

O código a seguir usa uma imagem local do pacote do aplicativo. Esse tipo de imagem está incluído no arquivo da solução do Visual Studio e é empacotado como parte do seu aplicativo. Essas imagens são acessadas usando o prefixo "ms-appx:///". Como prática recomendada, também atribuímos um texto alternativo opcional para fins de acessibilidade, como leitores de tela.



((XmlElement)tileImageAttributes[0]).SetAttribute("src", "ms-appx:///assets/redWide.png");
((XmlElement)tileImageAttributes[0]).SetAttribute("alt", "red graphic");

O código a seguir usa uma imagem local do armazenamento local do aplicativo. Esse tipo de imagem foi salvo pelo aplicativo no armazenamento local. Este é o local que o Windows.Storage.ApplicationData.Current.LocalFolder retorna. Essas imagens são acessadas com o uso do prefixo "ms-appdata:///local/". Mais uma vez, também atribuímos um texto alternativo opcional para fins de acessibilidade, como leitores de tela.



((XmlElement)tileImageAttributes[0]).SetAttribute("src", "ms-appdata:///local/redWide.png");
((XmlElement)tileImageAttributes[0]).SetAttribute("alt", "red graphic");

O código a seguir usa uma imagem da Web. Essas imagens são acessadas usando o protocolo "http://" ou "https://" para especificar o caminho da imagem. Observe que o aplicativo deve ter a funcionalidade internetClient declarada em seu manifesto para usar imagens da Web.



((XmlElement)tileImageAttributes[0]).SetAttribute("src", "http://www.contoso.com/redWide.png");
((XmlElement)tileImageAttributes[0]).SetAttribute("alt", "red graphic");

Você pode usar o atributo opcional baseUri para especificar um caminho raiz, como "http://www.contoso.com/", que é combinado com qualquer URI (Uniform Resource Identifier) relativo especificado nos atributos src de qualquer imagem. Esse atributo pode ser definido no elemento visual (a ser aplicado à notificação inteira) ou no elemento binding (a ser aplicado a essa associação). Se baseUri estiver definido nos dois, o valor em binding substituirá o valor em visual.

Se baseUri foi definido como "http://www.contoso.com/", esta linha no código de exemplo:



((XmlElement)tileImageAttributes[0]).SetAttribute("src", "http://www.contoso.com/redWide.png");

poderá ser encurtada para:



((XmlElement)tileImageAttributes[0]).SetAttribute("src", "redWide.png");

5. Incluir uma notificação quadrada e larga na carga

O usuário pode redimensionar seu bloco na tela inicial a qualquer momento, e não é possível saber em que estado (pequeno, médio, largo ou grande) o bloco se encontra quando você envia uma notificação. Se o seu bloco estiver dimensionado de tal forma que não exista uma associação de modelo correspondente na sua notificação, esta última não será exibida. Portanto, é uma prática recomendada sempre incluir versões da notificação em sua carga para todos os tamanhos de Live Tile (médio, largo, grande) para os quais você forneceu uma imagem de logotipo em seu manifesto.

Observação  A partir do Windows Phone 8.1, blocos grandes não são suportados no telefone.

Este exemplo define uma notificação média somente texto usando a mesma cadeia de caracteres de texto que usamos na notificação larga.



XmlDocument squareTileXml = TileUpdateManager.GetTemplateContent(TileTemplateType.TileSquare150x150Text04);

XmlNodeList squareTileTextAttributes = squareTileXml.GetElementsByTagName("text");
squareTileTextAttributes[0].AppendChild(squareTileXml.CreateTextNode("Hello World! My very own tile notification"));

Em seguida, adicione o bloco médio à carga do bloco largo. Recupere o elemento binding que define o bloco médio na carga squareTileXml. Acrescente esse elemento binding como irmão do bloco largo.



IXmlNode node = tileXml.ImportNode(squareTileXml.GetElementsByTagName("binding").Item(0), true);
tileXml.GetElementsByTagName("visual").Item(0).AppendChild(node);

As etapas anteriores resultam em dois elementos binding em um único elemento visual na carga XML, conforme mostrado aqui:



<tile>
    <visual version="2">
        <binding template="TileWide310x150ImageAndText01" fallback="TileWideImageandText01">
            <image id="1" src="ms-appx:///assets/redWide.png"/>
            <text id="1">Hello World! My very own tile notification</text>
        </binding>

        <binding template="TileSquare150x150Text04" fallback="TileSquareText04">
            <text id="1">Hello World! My very own tile notification</text>
        </binding>
    </visual>
</tile>

6. Criar a notificação com base no conteúdo XML que você especificou


TileNotification tileNotification = new TileNotification(tileXml);

7. Definir um tempo de expiração para a notificação

Por padrão, as notificações locais de bloco e selo não expiram, e as notificações por push, periódicas e agendadas expiram após três dias. Uma prática recomendada é definir um tempo de expiração, principalmente nas notificações locais de bloco e selo, usando um tempo que faça sentido para o seu aplicativo. O conteúdo do bloco só deve persistir enquanto for relevante. Neste caso, a notificação vai expirar e ser removida do bloco em dez minutos.


tileNotification.ExpirationTime = DateTimeOffset.UtcNow.AddMinutes(10);

8. Envie a notificação para o bloco do aplicativo.


TileUpdateManager.CreateTileUpdaterForApplication().Update(tileNotification);

9. Opcional: limpar sua notificação de bloco

Este exemplo mostra como limpar uma notificação de bloco através de uma chamada local. Se o conteúdo estiver associado a um tempo, observe que nós recomendamos que você defina um tempo de expiração na notificação, em vez de limpá-la explicitamente. A linha de código a seguir limpa a notificação atual do bloco do aplicativo.



Windows.UI.Notifications.TileUpdateManager.CreateTileUpdaterForApplication().Clear();

Em um bloco que tem a fila de notificação habilitada e com notificações, chamar o método Clear esvazia a fila.

Observe que você não pode limpar uma notificação da nuvem. Uma chamada local para o método Clear limpa o bloco independentemente da origem de suas notificações, mas as notificações periódicas ou por push só podem atualizar o bloco para um novo conteúdo.

Resumo e próximas etapas

Neste Guia de início rápido, você definiu e enviou um novo conteúdo para o bloco do seu aplicativo por meio de uma notificação, que depois foi removida após 10 minutos. O código a seguir resume as etapas acima, desde a escolha de um modelo até o envio da notificação. Ele usa uma imagem do pacote do aplicativo.

Para testar esse código em um exemplo de sua preferência, coloque-o em uma função que é acionada por um botão na interface do usuário do exemplo. Por exemplo, você pode colocar o botão no arquivo default.html. Lembre-se de substituir o nome de uma imagem real.



using Windows.UI.Notifications;
using Windows.Data.Xml.Dom;

XmlDocument tileXml = TileUpdateManager.GetTemplateContent(TileTemplateType.TileWide310x150ImageAndText01);

XmlNodeList tileTextAttributes = tileXml.GetElementsByTagName("text");
tileTextAttributes[0].InnerText = "Hello World! My very own tile notification";

XmlNodeList tileImageAttributes = tileXml.GetElementsByTagName("image");
((XmlElement)tileImageAttributes[0]).SetAttribute("src", "ms-appx:///assets/redWide.png");
((XmlElement)tileImageAttributes[0]).SetAttribute("alt", "red graphic");

XmlDocument squareTileXml = TileUpdateManager.GetTemplateContent(TileTemplateType.TileSquare150x150Text04);
XmlNodeList squareTileTextAttributes = squareTileXml.GetElementsByTagName("text");
squareTileTextAttributes[0].AppendChild(squareTileXml.CreateTextNode("Hello World! My very own tile notification"));
IXmlNode node = tileXml.ImportNode(squareTileXml.GetElementsByTagName("binding").Item(0), true);
tileXml.GetElementsByTagName("visual").Item(0).AppendChild(node);

TileNotification tileNotification = new TileNotification(tileXml);

tileNotification.ExpirationTime = DateTimeOffset.UtcNow.AddSeconds(10);

TileUpdateManager.CreateTileUpdaterForApplication().Update(tileNotification);

Agora que você atualizou o seu bloco pela primeira vez, é possível expandir sua funcionalidade habilitando uma fila de notificação.

Este Guia de início rápido enviou a atualização de bloco como uma notificação local. Você também pode explorar os outros métodos de distribuição de notificações: agendada, periódica e por push. Para saber mais, veja Entregando notificações.

Tópicos relacionados

Amostra de blocos e selos de aplicativo
Tamanhos de imagens de bloco e notificação do sistema
Visão geral de blocos e notificações de bloco
Diretrizes e lista de verificação de blocos
Como agendar uma notificação de bloco
Como configurar notificações periódicas para blocos
Guia de início rápido: criando um bloco padrão usando o editor de manifesto do Visual Studio
O catálogo de modelos de bloco
Esquema XML de blocos
Windows.UI.Notifications

 

 

Mostrar:
© 2017 Microsoft