Primary Live Tile API - Windows 10


New in Creators Update: You can finally programmatically pin your own app's primary tile to Start, just like secondary tiles! And you can check if it's currently pinned. You must target SDK 15063 or newer and be running Insider build 15063 or newer to use the primary tile API.

At its core, the API lets you...

  • Check if Start supports your app
  • Check if you're currently pinned
  • Pin your primary tile

Before we get started: UX best practices

You put a lot of effort into designing a great experience for your app’s primary tile, and now you have the opportunity to ask the user to pin it to Start. But before we dive into the code, here are some things to keep in mind as you’re designing your experience:

  • Do: Craft a non-disruptive and easily dismissible UX in your app with a clear "Pin Live Tile" call to action
  • Do: Clearly explain the value of your app’s Live Tile before asking the user to pin it
  • Don't: Ask a user to pin your app’s tile if the tile is already pinned or the device doesn’t support it (more info below)
  • Don't: Repeatedly ask the user to pin your app’s tile (they will probably get annoyed!)
  • Don't: Call the pin API without explicit user interaction or when your app is minimized/not open

Checking whether the API exists

If your app supports older versions of Windows 10, you need to check whether these primary tile API's are available. You do this by using ApiInformation. If the primary tile API's aren't available, avoid executing any calls to the API's.

if (ApiInformation.IsTypePresent("Windows.UI.StartScreen.StartScreenManager"))
{
    // Primary tile API supported!
}

else
{
    // Older version of Windows, no primary tile API
}

Check if Start supports your app

Depending on the current Start menu, and your type of app, pinning your app to the current Start screen might not be supported. Only Desktop and Mobile support pinning the primary tile to Start. Therefore, before showing any pin UI or executing any pin code, you first need to check if your app is even supported for the current Start screen. If it's not supported, don't prompt the user to pin the tile.

// Get your own app list entry
// (which is always the first app list entry assuming you are not a multi-app package)
AppListEntry entry = (await Package.Current.GetAppListEntriesAsync())[0];

// Check if Start supports your app
bool isSupported = StartScreenManager.GetDefault().SupportsAppListEntry(entry);

Check if you're currently pinned

To find out if your primary tile is currently pinned to Start, use the ContainsAppListEntryAsync method.

// Get your own app list entry
AppListEntry entry = (await Package.Current.GetAppListEntriesAsync())[0];

// Check if your app is currently pinned
bool isPinned = await StartScreenManager.GetDefault().ContainsAppListEntryAsync(entry);

Pin your primary tile

If your primary tile isn't currently pinned, and your tile is supported by Start, you might want to show a tip to users that they can pin your primary tile.

Note: You must call this API from a UI thread while your app is in the foreground, and you should only call this API after the user has intentionally requested the primary tile be pinned (for example, after the user clicked yes to your tip about pinning the tile).

If the user clicks your button to pin the primary tile, you would then call the RequestAddAppListEntryAsync method to request that your tile be pinned to Start. This will display a dialog asking the user to confirm that they want your tile pinned to Start.

This will return a boolean representing whether your tile is now pinned to Start. If your tile was already pinned, this will immediately return true without showing the dialog to the user. If the user clicks no on the dialog, or pinning your tile to Start isn't supported, this will return false. Otherwise, the user clicked yes and the tile was pinned, and the API will return true.

// Get your own app list entry
AppListEntry entry = (await Package.Current.GetAppListEntriesAsync())[0];

// And pin it to Start
bool isPinned = await StartScreenManager.GetDefault().RequestAddAppListEntryAsync(entry);

Resources

Comments (4)

  1. taperecorder says:

    CS0103 „StartScreenManager” does not exist in the current context

    1. andrewbares7 says:

      Are you sure you're using the latest SDK? You need to switch your project to target SDK 15063.

      1. keepsmestupid says:

        Get "Cannot create a file when that file already exists"
        Which file? Name? Path?

        1. andrewbares7 says:

          Hey, can you give us more info? What SDK version are you using? What device are you running it on? What OS version is that device on? And at what point is that exception occuring?

Skip to main content