Chaseable Tiles - Know what was clicked on your Live Tile (Windows 10 UWP)


New in Anniversary Update (build 14393 or newer): Apps can now know what tile notifications were displayed on their Tile when the user clicked it. For example, the News app can make sure that the story the user saw on the Live Tile is visible inside the app when launched.

We've added a new arguments property to the tile notification payload, similar to the arguments property on the toast notification payload.

In conjunction with that, we are providing the following new information, so that apps know...

  • The user launched their app via the tile rather than taskbar/apps list/search
  • The arguments from the current/recently displayed tile notifications

Guidance on implementing Chasesable Tiles

Chaseable Tiles are typically used when you are using the notification queue on your Live Tile (which means you are cycling through up to 5 different notifications). In addition to that, they're also primarily beneficial for when the content on your Live Tile is potentially not in sync with the latest content in the app. For example, a News app uses periodic Tile polling every 30 minutes to refresh the Live Tile's content, 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). In this case, the user might get frustrated about not being able to find the story they saw on their Live Tile. That's where Chaseable Tiles can help, by allowing you to make sure that what the user saw on their Tile is easily discoverable.

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. 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.

For example, if MSN News adds Chaseable Tiles, clicking on the Live Tile will launch their app normally (bringing them to the home page, or to whichever article they were previously reading). However, on the home page, they will ensure that the story from the Live Tile is easily discoverable on the home page. That way, both the scenario where you simply want to launch/resume the app, and the scenario where you want to view the specific story, are both functional.

Include the arguments property in your tile notification payload

The arguments property allows your app to provide the data necessary 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. 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 is lightweight.

The property can be set on both the <visual> and the <binding> elements, and will cascade down. If you want the same arguments on every tile size, simply set the arguments on the <visual>. If you need specific arguments for specific tile sizes, you can set the arguments on individual <binding> elements.

<tile>
  <visual arguments="action=storyClicked&amp;story=201c9b1">

    <binding template="TileMedium">
      
      <text>Son guilty of ...</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>Before San Bernardino...</text>
      ... (another story)
      ... (one more story)
  
    </binding>

  </visual>
</tile>
// Uses the following NuGet packages
// - Microsoft.Toolkit.Uwp.Notifications (1.0.0)
// - 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 */ }
        }
    }
};

Use the App.xaml.cs OnLaunched information

On the LaunchActivatedEventArgs object, there's a new property: TileActivatedInfo. When the user launches your app from the tile (rather than the app list, search, or any other entry point), this property will be initialized.

The TileActivatedInfo class 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.

Each ShownTileNotification has an Arguments property. 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("Windows.ApplicationModel.Activation.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
}

Resources

Comments (5)

  1. Vladislav says:

    It's really great and useful feature!

  2. Russty says:

    So I know the arguments of say the four tiles that were recently displayed. How do I find the argument of the one tile that was displaying when the user actually clicked it?

    By the way the 'e' in here should be 'args'

     string[] allArgs = e.TileActivatedInfo.RecentlyShownNotifications
                   .Select(i => i.Arguments)
                   .ToArray();
    Thanks,
    Russ

    1. Russty says:

      Okay maybe I should have read the guidance first..

      But the 'e' is still incorrect 🙂

      1. andrewbares7 says:

        Thanks for that correction Russty, updated the doc to use the correct variable! And yep, the first one is the one that the user "clicked" - remember that the user also might just want to launch your app normally, so you typically don't want to directly navigate to what they "clicked" in case they just wanted to launch your app 🙂

  3. Why not call them Trackable Tiles instead?

Skip to main content