When you submit an app to the Windows Phone Store, you have the option to offer a free trial of your app. There will be only one version of your app in the Store, but you can design your app to adapt its functionality based on the installed license. A user can tap Try to install your app free of charge. Along with the app, a trial license will be installed. The user can tap Buy to install a Full mode license. This sample shows you how to design your app to detect its license state when the app launches, and to detect changes to the license state while running. It can adapt features and functions accordingly. You could, for example, decide to limit functionality in trial mode, or you could turn off ads in full mode.
Follow the steps below to take the sample on a test drive.
To run the sample
Start Visual Studio Express 2012 for Windows Phone and select File > Open > Project/Solution.
Go to the directory in which you unzipped the sample. Double-click the Visual Studio Express 2012 for Windows Phone solution (.sln) file.
Confirm that the solution configuration drop-down list is set to Debug and then, on the Build menu, click Build Solution. (Ctrl+Shift+B)
On the Debug menu, click Start Without Debugging. (Ctrl+F5)
The first panorama page (Instructions) reports that you are running a debug build of the sample. There also are instructions on customizing the way that your app responds when the user taps Buy, and a report of the current settings. The second page (About) contains a label that indicates the current license mode (Trial mode) along with a Buy button. An About page is a good place to put a Buy button, but you also could put one on your main page if you like. The sample has a Buy button and a menu item on the app bar.
Tap either one of the Buy buttons, or the menu item. This launches the Store details page for the sample. However, the sample doesn't exist in the Store (and neither will your app until it is published) so in the sample a dialog is expected, which displays “Error code: 805a0194”.
Tap Close or Back to simulate completing the app purchase. The label on the About page now indicates a Full mode license. The Buy buttons and the menu item are disabled. In your app you could choose to remove them completely; perhaps you’d replace them with a message that thanks the user for purchasing your app.
Building and running the sample in release configuration doesn’t simulate the purchase experience, and it will not help you test the logic to check for a license in your own app. However, you will eventually publish a release build to the Store.
What’s in the project?
The sample has two parts. The first and most important piece is the TrialExperienceHelper class (SdkHelper namespace), which you'll find in the SdkHelper folder. You can use that class without modification in your own projects. The following sections describe this class, how it works, and how you can use it in your own app.
The second part of this sample is the example UI and view model that makes up the rest of the sample. The view model is in the ViewModel folder and it shows you how you can customize your use of the general-purpose TrialExperienceHelper class for a particular app. The view model in this sample has string properties, in addition to BuyCommand, to which the UI binds. Your app won't need those string properties, but you might find BuyCommand useful. We’ve also included (in the SdkHelper folder) standard, generally useful, helper implementations of INotifyPropertyChanged and ICommand.
Which licensing APIs are used?
The TrialExperienceHelper class determines license state by querying the IsActive and IsTrial properties of the LicenseInformation class. It does this only when necessary – once when the app launches, and then each time the app resumes. It caches the results, so your app code can query the TrialExperienceHelper.LicenseMode property as often as you like without the app paying a performance penalty. The LicenseMode property returns a value from the LicenseModes enum (Full, MissingOrRevoked, or Trial) so that your app code needs to check only a single value. There’s also a convenient Boolean IsFull property. Whenever the license mode has changed, or it is likely to have changed, TrialExperienceHelper raises its LicenseChanged event and your app code can handle that event to query LicenseMode or IsFull again. Then, your app can control the availability of features, ads, and your Buy UI as needed.
Using TrialExperienceHelper in debug and release configurations
When you develop your app, you can write your own view model to consume TrialExperienceHelper, or you can consume the helper using the code-behind. The code you use to consume the helper will be the same in debug configuration and in release configuration. In debug configuration, the helper simulates a purchase so you can verify that your code responds to its LicenseChanged event and property values correctly. The app you eventually publish to the Store will be a release build. In that build, the helper's simulation is removed by conditional compilation, but the helper functions the same in relation to your code. The difference is that the helper will access the app’s actual license info at that time.