Windows Store object

Note: this plugin was formerly named the Windows 8 object.

The Windows Store object provides access to platform-specific features available when running as a Windows Store (UWP) app. This is supported by Windows 8 and newer (including Windows 10). Note these features do not apply when running from the desktop, even in Internet Explorer or Edge - they only work in the new style Windows Store apps that run from the start menu.

Windows Store apps also support touch input, which is sometimes the only input method available for Windows-based phones and tablets. To support these devices be sure to add the Touch object and support touch controls.

Roaming data

The object's features to use roaming data are designed to be used the same way as the WebStorage object. Familiarity with WebStorage will make it easier to use the roaming data features. The main difference between WebStorage and roaming data is that in Windows Store apps, roaming data is synced between all the user's devices.

As with WebStorage, all roaming data values are strings. You can store numbers in roaming data, but they are automatically converted to strings. To convert a string back to a number, use the int() or float() system expressions.

Test mode

Enabling the Test mode property of the Windows Store object allows you to test purchases work before publishing to the Windows Store and without having to spend any money. However you must turn Test mode off before submitting to the Windows Store, otherwise your app will be rejected.

While in test mode, at startup a message will appear every run reminding you the app is in test mode. The purchase state is then loaded from WindowsStoreProxy.xml which you can use to simulate various states of trial, purchase, item sales, and so on. The various purchase related conditions, actions and expressions will then work based on the simulated state. Note nothing you do in the app will affect the content of WindowsStoreProxy.xml - it only affects the currently running session and will reset to the XML's description on the next run.

About, Support and Privacy settings

By default the Windows Store object adds three options to the Settings charm: About (for general and version information), Support (information on where users can get help for your application), and Privacy (a page including the privacy policy for your application). These can be enabled or disabled individually in the Windows Store object's properties.

It is highly recommended to include all of these settings if possible, since doing so can help your application be approved in the Windows Store. In some cases, a privacy policy is also actually required.

After exporting, your export folder will contain three HTML files: about.html, support.html and privacy.html. You should edit the content of these files as appropriate for your application.

Windows Store conditions

Has product
Test if a given product ID (case sensitive) has been purchased by the current user. This condition is subject to Test Mode.

Is expired trial
Test if the app is in trial mode, and the trial period has expired. This condition is subject to Test Mode.

Is licensed
Test if the app has been successfully purchased by the current user and has a valid license. This condition is subject to Test Mode.

Is trial
Test if the app is in trial mode, and the trial is active (the trial period has not expired). This condition is subject to Test Mode.

On failed purchase
Triggered after a purchase attempt is cancelled or otherwise completes unsuccessfully.

On license changed
Triggered when the license state of the app has changed, such as going from trial to licensed, or trial to expired trial. This condition is subject to Test Mode.

On store listing received
Triggered after the Request store listing action has completed. The store listing expressions can then be used.

On successful purchase
Triggered after a purchase attempt completes successfully. Either the app or a new product is now owned by the user.

On data changed
Triggered when the roaming data has been updated with data from another device. Typically this happens when saving roaming data on one device, then the user switches to another device, and runs the same app again. There may be a delay before roaming data syncs up, and when it is ready this trigger fires.

Roaming key exists
True if a given key name exists in roaming storage.

On share
Triggered when the user activates the Share charm. In order to specify what to share, use one of the sharing actions in this trigger.

Is Windows 8 app
True if currently running specifically as a Windows 8 app, otherwise false. Note this condition tests specifically Windows 8 - it is not true on Windows 10, even though it supports Windows Store apps. You may prefer to use the Is Windows Store app condition instead.

Is Windows Store app
True if currently running as a Windows Store app on any version of Windows that supports Store apps (8/8.1/10+). If false, none of the object's Windows-specific features will work.

Windows Store actions

Set live tile text
Change the app's tile in the start menu to display some text. A pre-defined template must be chosen to determine the layout. For previews, see the tile template catalog on MSDN. Note that using the wide templates requires that your app already be using a wide tile; setting a live tile text to a template which is a different size to your app's current tile will not work.

Open Windows Store
Open the Windows Store to a specific page: the listing page for the current app, the page for the publisher of the current app, or a page where the user can submit a review of the app. These may not work until the app is published to the Windows Store.

Purchase app
Prompt the user to purchase the app. You should only use this action when the user expects it, such as when they pressed a 'Purchase' button. If the purchase is successful, On successful purchase and On license changed are triggered. Otherwise On failed purchase is triggered. This action is subject to Test Mode.

Purchase product
Prompt the user to purchase a specific product ID (case sensitive). You should only use this action when the user expects it, such as when they pressed a 'Purchase' button. If successful, On successful purchase triggers; otherwise On failed purchase triggers. This action is subject to Test Mode.

Request store listing
Request details about items available for purchase with this app. When the details are received, On store listing received triggers and the store listing expressions can be used.

Clear roaming data
Remove all keys from roaming data, reverting it to an empty state.

Remove roaming value
Remove a specific key from roaming data.

Set roaming value
Store a key and an associated value in roaming data. If it does not exist, it is created. If it already exists, its value is overwritten. Values are always stored as strings. You can use a number for the value, but it will be converted to a string before being stored, and will be returned by the object as a string.

Fail share
Only valid in an On share event. Use this action to indicate sharing failed or is currently unavailable.

Share data URI
Only valid in an On share event. Use this action to share an image encoded as a data URI from the application. This is most useful with the Snapshot canvas system action, which returns a screenshot of the game as a data URI.

Share HTML
Only valid in an On share event. Use this action to share some HTML formatted text from the application.

Share link
Only valid in an On share event. Use this action to share a link, such as the address of your website, from the application.

Share sprite image
Only valid in an On share event. Use this action to share an image from the application, using a Sprite object's current image as the image to share.

Share text
Only valid in an On share event. Use this action to share some plain text from the application.

Show share UI
Bring up the Windows 8 Share UI automatically. Note this was removed in Windows 10. Be sure to use this with care in a way that will not offend or come across as obnoxious to your users. For example a sensible use is a custom Share button in your application which brings up the Share UI. This action only works when your app is in the foreground.

Set back button visible
Show or hide an optional "Back" button in the caption of a restored Windows 10 app on desktop. This has no effect on mobile. When the "Back" button in the caption is clicked, it will fire the Browser object's On back button trigger.

Windows Store expressions

TrialTimeLeft
If in trial mode, returns the number of seconds in the trial period remaining. If not in a time-limited trial mode the returned value will be meaningless (such as a very large number to represent an indefinite trial time). This expression is subject to Test Mode.

RoamingValue(key)
Retrieve a value from roaming storage associated with the given key. If the key does not exist, an empty string is returned. Note all values are returned as strings, even if they were originally passed as numbers.

AppFormattedPrice
After On store listing received triggers, returns the price and currency of the app formatted for the user's region.

ProductFormattedPrice
After On store listing received triggers, returns the price and currency of a product ID formatted for the user's region.

ProductName
After On store listing received triggers, returns the user-friendly name of a product from its ID.

Tags: