Agrupando notificações toast com coleções

Use coleções para organizar os toasts do seu aplicativo na Central de Ações. As coleções ajudam os usuários a localizar informações na Central de Ações com mais facilidade e permitem que os desenvolvedores gerenciem melhor suas notificações. As APIs abaixo permitem remover, criar e atualizar coleções de notificações.

Você pode ver o exemplo abaixo com um aplicativo de mensagens que separa as notificações com base no grupo de chat; cada título (Comp Sci 160A Project Chat, Direct Messages, Lacrosse Team Chat) é uma coleção separada. Observe como as notificações são agrupadas distintamente como se fossem de um aplicativo separado, mesmo que sejam todas notificações do mesmo aplicativo. Se tu estiveres à procura de uma maneira mais subtil de organizar as tuas notificações, consulta cabeçalhos de avisos.

Criação de coleções

Ao criar cada coleção, é necessário fornecer um nome para exibição e um ícone, que são exibidos dentro da Central de Ações como parte do título da coleção, conforme mostrado na imagem acima. As coleções também exigem um argumento de inicialização para ajudar o aplicativo a navegar para o local certo dentro do aplicativo quando o título da coleção é clicado pelo usuário.

Criar uma coleção

// Create a toast collection
public async void CreateToastCollection()
{
	string displayName = "Work Email"; 
	string launchArg = "NavigateToWorkEmailInbox"; 
	Uri icon = new Windows.Foundation.Uri("ms-appx:///Assets/workEmail.png");

	// Constructor
	ToastCollection workEmailToastCollection = new ToastCollection(
		"MyToastCollection", 
		displayName,
 		launchArg, 
		icon);

	// Calls the platform to create the collection
	await ToastNotificationManager.GetDefault().GetToastCollectionManager().SaveToastCollectionAsync(workEmailToastCollection);  								
}

Enviar notificações para uma coleção

Abordaremos o envio de notificações de três pipelines de toast diferentes: local, agendado e push. Para cada um desses exemplos, criaremos uma mensagem de notificação para enviar utilizando o código imediatamente abaixo, e depois iremos concentrar-nos em como adicionar essa mensagem a uma coleção através de cada pipeline.

Construa o conteúdo da notificação toast

// Construct the content
var content = new ToastContentBuilder()
	.AddText("Adam sent a message to the group")
	.GetToastContent();

Enviar um toast para uma coleção

// Create the toast
ToastNotification toast = new ToastNotification(content.GetXml());

// Get the collection notifier
var notifier = await ToastNotificationManager.GetDefault().GetToastNotifierForToastCollectionIdAsync("MyToastCollection");

// And show the toast
notifier.Show(toast);

Adicionar um toast agendado a uma coleção

// Create scheduled toast from XML above
ScheduledToastNotification scheduledToast = new ScheduledToastNotification(content.GetXml(), DateTimeOffset.Now.AddSeconds(10));

// Get notifier
var notifier = await ToastNotificationManager.GetDefault().GetToastNotifierForToastCollectionIdAsync("MyToastCollection");
    
// Add to schedule
notifier.AddToSchedule(scheduledToast);

Enviar uma notificação push do tipo toast para uma coleção

Para notificações push, é necessário adicionar o cabeçalho X-WNS-CollectionId à mensagem POST.

// Add header to HTTP request
request.Headers.Add("X-WNS-CollectionId", collectionId); 

Gestão de coleções

Criar o gestor de coleção de notificações tipo "toast"

Para o resto dos trechos de código nesta seção 'Gerenciando coleções', usaremos o collectionManager abaixo.

ToastCollectionManger collectionManager = ToastNotificationManager.GetDefault().GetToastCollectionManager();

Obter todas as coleções

IReadOnlyList<ToastCollection> collections = await collectionManager.FindAllToastCollectionsAsync();

Obter o número de coleções criadas

int toastCollectionCount = (await collectionManager.FindAllToastCollectionsAsync()).Count;

Remover uma coleção

await collectionManager.RemoveToastCollectionAsync("MyToastCollection");

Atualizar uma coleção

Você pode atualizar coleções criando uma nova coleção com a mesma ID e salvando a nova instância da coleção.

string displayName = "Updated Display Name"; 
string launchArg = "UpdatedLaunchArgs"; 
Uri icon = new Windows.Foundation.Uri("ms-appx:///Assets/updatedPicture.png");

// Construct a new toast collection with the same collection id
ToastCollection updatedToastCollection = new ToastCollection(
	"MyToastCollection", 
	displayName,
	launchArg, 
	icon);

// Calls the platform to update the collection by saving the new instance
await collectionManager.SaveToastCollectionAsync(updatedToastCollection);  								

Gerenciando notificações do sistema em uma coleção

Propriedades de grupo e tag

As propriedades de grupo e tag juntas identificam exclusivamente uma notificação dentro de uma coleção. Grupo (e Tag) serve como uma chave primária composta (mais de um identificador) para identificar sua notificação. Por exemplo, se pretender remover ou substituir uma notificação, tem de ser capaz de especificar qual a notificação que pretende remover/substituir; você faz isso especificando a tag e o grupo. Um exemplo é um aplicativo de mensagens. O desenvolvedor pode usar o ID da conversa como o Grupo e o ID da mensagem como a Tag.

Remover uma notificação do sistema de uma coleção

Você pode remover notificações individuais usando as IDs de tag e grupo ou limpar todas as notificações de um grupo.

// Get the history
var collectionHistory = await ToastNotificationManager.GetDefault().GetHistoryForToastCollectionAsync("MyToastCollection");

// Remove toast
collectionHistory.Remove(tag, group); 

Limpar todos os toasts numa coleção

// Get the history
var collectionHistory = await ToastNotificationManager.GetDefault().GetHistoryForToastCollectionAsync("MyToastCollection");

// Remove toast
collectionHistory.Clear();

Coleções no Visualizador de Notificações

Você pode usar a ferramenta Visualizador de notificações para ajudar a projetar suas coleções. Siga os passos abaixo:

• Clique no ícone de engrenagem no canto inferior direito.
• Selecione 'Coleções Toast'.
• Acima da visualização da notificação toast, há um menu suspenso 'Coleção de Toasts'. Selecione gerenciar coleções.
• Clique em 'Adicionar coleção', preencha os detalhes da coleção e salve.
• Você pode adicionar mais coleções ou clicar fora da caixa gerenciar coleções para retornar à tela principal.
• Selecione a coleção à qual deseja adicionar a notificação do tipo 'toast' a partir do menu suspenso 'Toast Collection'.
• Quando se disparar o toast, ele será adicionado à coleção apropriada no Centro de Ações.

Outros detalhes

As coleções de notificações que são criadas também se refletirão nas configurações de notificação do utilizador. Os usuários podem alternar as configurações de cada coleção individual para ativar ou desativar esses subgrupos. Se as notificações estiverem desativadas no nível superior do aplicativo, todas as notificações de cobranças também serão desativadas. Além disso, cada coleção mostrará por padrão 3 notificações na Central de Ações, e o usuário pode expandi-la para mostrar até 20 notificações.

Tópicos relacionados

• Conteúdo do sistema
• Cabeçalhos de notificação
• Biblioteca de notificações no GitHub (parte do Kit de Ferramentas da Comunidade do Windows)