可追踪的磁贴通知

项目
12/29/2023

可追踪磁贴通知可以让你决定在用户单击磁贴时，应用的动态磁贴显示哪个磁贴通知。
例如，新闻应用可以使用此功能来确定用户启动时动态磁贴显示哪些新闻故事;它可以确保该故事突出显示，以便用户可以找到它。

重要

需要周年更新：若要将可追踪磁贴通知与 C#、C++ 或基于 VB 的 UWP 应用配合使用，必须以 SDK 14393 为目标并运行版本 14393 或更高版本。对于基于 JavaScript 的 UWP 应用，必须以 SDK 17134 为目标并运行版本 17134 或更高版本。

重要 API：LaunchActivatedEventArgs.TileActivatedInfo 属性，TileActivatedInfo 类

工作原理

若要启用可追踪磁贴通知，请使用磁贴通知有效负载上的“参数”属性（类似于 toast 通知有效负载上的启动属性）在磁贴通知中嵌入有关内容的信息。

通过动态磁贴启动应用时，系统会从当前/最近显示的磁贴通知中返回参数列表。

何时使用可追踪的磁贴通知

使用动态磁贴上的通知队列时，通常会使用可追踪磁贴通知（这意味着你正在循环访问最多 5 个不同的通知）。当动态磁贴上的内容可能与应用中的最新内容不同步时，追踪磁贴通知也很有用。例如，新闻应用会每隔 30 分钟刷新其动态磁贴，但当应用启动时，它会加载最新新闻（这可能不包括上次轮询间隔中的磁贴上的内容）。发生这种情况时，用户可能会对无法找到他们在动态磁贴上看到的故事感到沮丧。这就是可追踪磁贴通知可以提供帮助的地方，让你确保用户在其磁贴上看到的内容更容易被发现。

可追踪磁贴通知的用途

需要注意的最重要事项是，在大多数情况下，用户单击磁贴时不应直接导航到磁贴上的特定通知。动态磁贴作为应用程序的入口点。用户单击你的动态磁贴时，可能有两种情况：(1) 他们希望正常启动你的应用，或者 (2) 他们希望查看有关动态磁贴上特定通知的详细信息。由于用户无法明确说明所需的行为，因此理想的体验是正常启动应用，同时确保用户看到的通知易于发现。

例如，单击 MSN 新闻应用的动态磁贴会正常启动该应用：它显示主页或用户以前阅读过的文章。但是，在主页上，应用可确保动态磁贴中的故事容易被发现。这样，这两种方案都受支持：只需启动/恢复应用的方案，以及要查看特定故事的方案。

如何在磁贴通知有效负载中包含“参数”属性

在通知有效负载中，参数属性使应用能够提供稍后可用于辨识通知的数据。例如，参数可能包含故事的 ID，以便在启动时取回和显示故事。该属性接受可以序列化的字符串（查询字符串、JSON 等），但我们通常建议使用查询字符串格式，因为它很轻量且 XML 编码良好。

可以在 TileVisual 和 TileBinding 元素上设置该属性，并将向下级联。如果需要每个磁贴大小的相同参数，只需在 TileVisual 上设置参数即可。如果需要特定磁贴大小的特定参数，可以在单个 TileBinding 元素上设置参数。

此示例创建一个使用参数属性的通知有效负载，以便以后可以识别通知。

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

如何在应用启动时检查参数属性

大多数应用都有一个 App.xaml.cs 文件，其中包含 OnLaunched 方法的替代。顾名思义，应用在启动时会调用此方法。它采用单个参数，即 LaunchActivatedEventArgs 对象。

LaunchActivatedEventArgs 对象具有一个启用可追踪通知的属性：TileActivatedInfo 属性，该属性提供对 TileActivatedInfo 对象的访问。当用户从其磁贴（而不是应用列表、搜索或任何其他入口点）启动应用时，应用将初始化此属性。

TileActivatedInfo 对象包含一个名为 RecentlyShownNotifications 的属性，其中包含过去 15 分钟内磁贴上显示的通知列表。列表中的第一项表示磁贴上的当前通知，后续项表示用户在当前项之前看到的通知。如果已清除磁贴，则此列表为空。

每个 ShownTileNotification 都有一个“参数”属性。 “参数”属性将使用磁贴通知有效负载中的参数字符串进行初始化；如果有效负载不包含参数字符串，则其为 null。

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
}

从桌面应用程序访问 OnLaunched

使用桌面桥的桌面应用（如 WPF 等）也可以使用可追踪磁贴！唯一的区别是访问 OnLaunched 参数。请注意，首先必须使用桌面桥打包应用。

重要

需要 2018 年 10 月更新：若要使用 AppInstance.GetActivatedEventArgs() API，必须以 SDK 17763 为目标并运行版本 17763 或更高版本。

对于桌面应用程序，若要访问启动参数，请执行以下...


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;

原始 XML 示例

如果使用原始 XML 而不是通知库，则是下面的 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>

可追踪的磁贴通知

工作原理

何时使用可追踪的磁贴通知

可追踪磁贴通知的用途

如何在磁贴通知有效负载中包含“参数”属性

如何在应用启动时检查参数属性

从桌面应用程序访问 OnLaunched

原始 XML 示例

反馈

其他资源

可追踪的磁贴通知

工作原理

何时使用可追踪的磁贴通知

可追踪磁贴通知的用途

如何在磁贴通知有效负载中包含“参数”属性

如何在应用启动时检查参数属性

从桌面应用程序访问 OnLaunched

原始 XML 示例

相关文章

反馈

其他资源