可追踪的磁贴通知Chaseable tile notifications

使用可追踪的磁贴通知可以由你决定用户单击磁贴时,应用的动态磁贴显示哪个磁贴通知。Chaseable tile notifications let you determine which tile notifications your app's Live Tile was displaying when the user clicked the tile.
例如,新应用可以使用此功能来决定用户启动应用时其动态磁贴显示哪一篇新闻报道,这样可以确保文章突出显示,以便用户找到它。For example, a news app could use this feature to determine which news story the its Live Tile was displaying when the user launched it; it could that ensure that the story is prominently displayed so that the user can find it.

重要

需要周年更新:若要通过 C#、C++ 或基于 VB 的 UWP 应用使用可追踪的磁贴通知,必须面向 SDK 14393 且必须运行版本 14393 或更高版本。Requires Anniversary Update: To use chaseable tile notifications with C#, C++, or VB-based UWP apps, you must target SDK 14393 and be running build 14393 or higher. 对于基于 JavaScript 的 UWP 应用,必须面向 SDK 17134 且必须运行版本 17134 或更高版本。For JavaScript-based UWP apps, you must target SDK 17134 and be running build 17134 or higher.

重要 APILaunchActivatedEventArgs.TileActivatedInfo 属性TileActivatedInfo 类Important APIs: LaunchActivatedEventArgs.TileActivatedInfo property, TileActivatedInfo class

工作原理How it works

若要启用可追踪的磁贴通知,请使用磁贴通知有效负载上的 Arguments 属性(类似于 toast 通知有效负载的 launch 属性)嵌入磁贴通知中的内容信息。To enable chaseable tile notifications, you use the Arguments property on the tile notification payload, similar to the launch property on the toast notification payload, to embed info about the content in the tile notification.

当应用通过动态磁贴启动时,系统将从当前/最近显示的磁贴通知返回参数列表。When your app is launched via the Live Tile, the system returns a list of arguments from the current/recently displayed tile notifications.

何时使用可追踪磁贴通知When to use chaseable tile notifications

当你在动态磁贴上使用通知队列时(说明你在循环使用多达 5 个不同通知),通常使用可追踪磁贴通知。Chaseable tile notifications are typically used when you're using the notification queue on your Live Tile (which means you are cycling through up to 5 different notifications). 另外,当动态磁贴上的内容可能与应用中的最新内容不同步时,可追踪磁贴通知也很有帮助。They're also beneficial when the content on your Live Tile is potentially out of sync with the latest content in the app. 例如,“新闻”应用每 30 分钟刷新一次动态磁贴,但当该应用启动时,它会加载最新的新闻(可能不会包括上次轮询间隔中磁贴上的内容)。For example, the News app refreshes its Live Tile every 30 minutes, but when the app is launched, it loads the latest news (which may not include something that was on the tile from the last polling interval). 发生这种情况时,用户可能会因为无法找到他们在动态磁贴上看见的新闻而感到沮丧。When this happens, the user might get frustrated about not being able to find the story they saw on their Live Tile. 这就是可追踪磁贴通知的用处所在,借助它可以确保用户能够轻松找到他们在磁贴上看到的内容。That's where chaseable tile notifications can help, by allowing you to make sure that what the user saw on their Tile is easily discoverable.

对可追踪磁贴通知的操作What to do with a chaseable tile notifications

请注意,最重要的是,在大多数情况下,当用户单击磁贴时,不应直接导航到磁贴上的特定通知The most important thing to note is that in most scenarios, you should NOT directly navigate to the specific notification that was on the Tile when the user clicked it. 动态磁贴用作的是应用程序的入口点。Your Live Tile is used as an entry point to your application. 当用户单击动态磁贴时可能有两种情况:(1) 他们希望正常启动应用或 (2) 他们希望看到有关动态磁贴上特定通知的详细信息。There can be two scenarios when a user clicks your Live Tile: (1) they wanted to launch your app normally, or (2) they wanted to see more information about a specific notification that was on the Live Tile. 由于无法让用户明确表示他们所需的是哪种行为,所以理想的体验是正常启动应用,并确保用户可以轻松找到其看到的通知Since there's no way for the user to explicitly say which behavior they want, the ideal experience is to launch your app normally, while making sure that the notification the user saw is easily discoverable.

例如,单击“MSN 资讯”应用的动态磁贴可正常启动应用:它会显示主页或用户之前阅读的文章。For example, clicking the MSN News app's Live Tile launches the app normally: it displays the home page, or whichever article the user was previously reading. 但是,在主页上,该应用可确保动态磁贴上显示的新闻可以轻松找到。However, on the home page, the app ensures that the story from the Live Tile is easily discoverable. 这样即可支持以下两种情况:仅想要启动/继续使用该应用的情况,以及想要查看具体新闻的情况。That way, both scenarios are supported: the scenario where you simply want to launch/resume the app, and the scenario where you want to view the specific story.

如何在磁贴通知有效负载中包含 Arguments 属性How to include the Arguments property in your tile notification payload

在通知有效负载中,Arguments 属性让应用能够提供以后可用来识别通知的数据。In a notification payload, the arguments property enables your app to provide data you can use to later identify the notification. 例如,参数可能包括新闻 ID,这样,当应用启动时,即可检索并显示该新闻。For example, your arguments might include the story's id, so that when launched, you can retrieve and display the story. 该属性接受字符串,根据需要可以进行序列化(查询字符串、JSON 等),但通常建议采用查询字符串格式,因为这是轻量的,采用 XML 进行精细编码。The property accepts a string, which can be serialized however you like (query string, JSON, etc), but we typically recommend query string format, since it's lightweight and XML-encodes nicely.

该属性可对 TileVisualTileBinding 元素进行设置并向下级联。The property can be set on both the TileVisual and the TileBinding elements, and will cascade down. 如果希望每个磁贴大小采用相同的参数,只需对 TileVisual 设置参数。If you want the same arguments on every tile size, simply set the arguments on the TileVisual. 如果需要对特定磁贴大小使用特定参数,可对个别 TileBinding 元素设置参数。If you need specific arguments for specific tile sizes, you can set the arguments on individual TileBinding elements.

本示例创建使用 Arguments 属性的通知有效负载,以便以后识别通知。This example creates a notification payload that uses the arguments property so that notification can be identified later.

// 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 */ }
        }
    }
};

在应用启动时如何检查参数属性How to check for the arguments property when your app launches

大部分应用都有一个包含 OnLaunched 方法的重写方法的 App.xaml.cs 文件。Most apps have an App.xaml.cs file that contains an override for the OnLaunched method. 顾名思义,应用在启动时调用此方法。As its name suggests, your app calls this method when it's launched. 它使用一个参数,即 LaunchActivatedEventArgs 对象。It takes a single argument, a LaunchActivatedEventArgs object.

LaunchActivatedEventArgs 对象有一个属性支持可追踪通知,那就是 TileActivatedInfo 属性,它提供对 TileActivatedInfo 对象的访问。The LaunchActivatedEventArgs object has a property that enables chaseable notifications: the TileActivatedInfo property, which provides access to a TileActivatedInfo object. 当用户从应用磁贴(而不是应用列表、搜索或任何其他入口点)启动应用时,它初始化此属性。When the user launches your app from its tile (rather than the app list, search, or any other entry point), your app initializes this property.

TileActivatedInfo 对象包含一个名为 RecentlyShownNotifications 的属性,其中包含在前 15 分钟内在磁贴上显示的通知的列表。The TileActivatedInfo object contains a property called RecentlyShownNotifications, which contains a list of notifications that have been shown on the tile within the last 15 minutes. 该列表中的第一项表示磁贴的当前通知,后面的项表示用户在当前通知之前看过的通知。The first item in the list represents the notification currently on the tile, and the subsequent items represent the notifications that the user saw before the current one. 如果已清除磁贴,则该列表为空。If your tile has been cleared, this list is empty.

每个 ShownTileNotification 都有一个 Arguments 属性。Each ShownTileNotification has an Arguments property. 如果负载不包括参数字符串,则使用磁贴通知负载中的参数字符串或 null 初始化 Arguments 属性。The Arguments property will be initialized with the arguments string from your tile notification payload, or null if your payload didn't include the arguments string.

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
}

从桌面应用程序访问 OnLaunchedAccessing OnLaunched from desktop applications

桌面应用程序 (如 WPF 等) 使用 桌面桥,还可以使用 chaseable 磁贴!Desktop apps (like WPF, etc) using the Desktop Bridge, can use chaseable tiles too! 唯一的区别是访问 OnLaunched 参数。The only difference is accessing the OnLaunched arguments. 请注意,必须首先 将你的应用与桌面桥打包Note that you first must package your app with the Desktop Bridge.

重要

需要10月2018更新:若要使用 AppInstance.GetActivatedEventArgs() API,你必须面向 SDK 17763,并运行版本17763或更高版本。Requires October 2018 Update: To use the AppInstance.GetActivatedEventArgs() API, you must target SDK 17763 and be running build 17763 or higher.

对于桌面应用程序,若要访问启动参数,请执行以下操作 .。。For desktop applications, to access the launch arguments, do the following...


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

    // API only available on build 17763 or higher
    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;

原始 XML 示例Raw XML example

如果使用原始 XML 而不是通知库,请查看下面的 XML。If you're using raw XML instead of the Notifications library, here's the 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>