[Preview] Primary Live Tile API’s – 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. Note that you must target Insider SDK 15003 and be running Insider build 15025 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: 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.

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.

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.