可追蹤式磚通知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 app 使用可追蹤式磚通知,您的目標必須是 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 app,您的目標必須是 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 屬性 (類似於快顯通知裝載上的 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

在通知裝載中,引數屬性可讓您的應用程式提供稍後用來找出通知的資料。In a notification payload, the arguments property enables your app to provide data you can use to later identify the notification. 例如,引數可能包含故事的識別碼,以便啟動時,您可以擷取並顯示故事。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.

此範例會建立使用引數屬性的通知承載,以便稍後識別通知。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

大部分應用程式有 App.xaml.cs 檔案,其中包含 OnLaunched 方法的覆寫。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. Arguments 屬性會使用磚通知裝載上的引數字串來初始化,而如果裝載未包含引數字串則為 null。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.

重要

需要2018年10月更新:若要使用 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>