PhoneGap on WP7 Tip #6: Trial Mode

When you provide users a way to evaluate your application without any money up front, your app turns into the best advertising for itself. The user can check out your application in a limited feature mode, and when you have them hooked in to the benefits, they’re more likely to spring the cash to buy it.

On many platforms, this entails maintaining separate versions of your applications, both in the source code and in the marketplace. Not so with Windows Phone.

The Windows Phone marketplace (and the forthcoming Windows 8 marketplace) provide you, the developer/publisher, the option of providing a trial mode for your application. When you publish your app with trial mode enabled, users will see two ways to get your app in the marketplace, like in this example with Angry Birds.

Note that this is a single location in the marketplace. Which means it’s a single version of your application. You don’t need to maintain two different code bases!

When the user installs the app using the “try” option, you can check a flag within your application whenever you want, and if the user installed it as a trial, you can limit what they can do. This trial mode limitation is completely up to you. You can allow them to play only a few levels of a game, limit them to adding 5 friends to some list, prevent them from saving an edited picture, whatever. The choice is yours.

With a PhoneGap application on Windows Phone, we can take advantage of the trial mode capability very easily.

First, take a look at this article for implementing trial mode in a Silverlight application (since that is what hosts a PhoneGap application). We’ll be using that as a basis for the code in this blog post.

Specifically, we’ll need to create an application level variable to store the value of the trial mode flag. We do this because checking the flag from the underlying marketplace API takes a little time to do, so for our app to be most responsive, we’ll cache that value in a variable. Also note in the article there are certain times when we ask the marketplace API for that value – when the application starts and when the application resumes. The reason we check it when it resumes is that the user can switch away from the running app, buy the app, then return immediately, and we want to be ready to expose all the features of our app in their full glory when the user comes back!

Open an existing PhoneGap project (or create a new PhoneGap project using the Visual Studio template as described here). Then, follow the section of the trial mode article above article entitled “Checking for a Trial License in Your Application”. That will enable us to cache the value of the trial mode flag. It also provides a way to test it, since when you’re developing, there’s no marketplace installation yet from which to pull the setting. This testing code is contained in a compiler directive #if DEBUG. When the application is published, you should change the value in the drop down at the top of the Visual Studio window from Debug to Release, and you won’t have to remove any of the code, it will just switch to using the other section in the #if directive.

Now that we have the trial mode value cached in our hosting Silverlight application, let’s access it from the code in our PhoneGap application. We’re going to use a Plugin as described in my previous post about SMS messages. The difference here is that when we used a Plugin to send an SMS message, it was fire and forget, and in this case the Plugin must now return that trial mode flag.

We’ll create the C# code first for the Plugin. Right click on the Plugins folder in your project in Solution Explorer, and create a new class called Marketplace.cs. In that class we’ll put the code that our Plugin is going to call. Replace all the code in that class with the following. Note the namespace is important, it ties this class to the PhoneGap Plugin plumbing.

 using System;
 using System.Net;
 using System.Windows;
  
 namespace WP7GapClassLib.PhoneGap.Commands
 {
     public class Marketplace : BaseCommand
     {
         public void checkLicense(string args)
         {
             PluginResult result = new PluginResult(PluginResult.Status.OK, (Application.Current as PGWP7_Trial.App).IsTrial);
             
             this.DispatchCommandResult(result);
         }
     }
 }

This Plugin references our IsTrial variable created in the above article on trial mode, so it’s important to realize it won’t work without that code.

Now that we have the function in the Plugin, we can invoke it from JavaScript inside our PhoneGap application. We’ll create a separate .js file to handle calling into the Plugin framework. Add a new text file in the www folder in the project, named marketplace.js.

 function marketplace() {
     this.resultCallback = null;
 }
  
 marketplace.prototype.checkLicense = function (callback) {
     var args = {}
     PhoneGap.exec(callback, null, "Marketplace", "checkLicense", args);
  
 }
  
  
 PhoneGap.addConstructor(function () {
     if (!window.plugins) {
         window.plugins = {};
     }
     window.plugins.marketplace = new marketplace();
     }
   );

This handles the call to the C# code above and makes the Plugin available to the rest of the code in the PhoneGap project.

Here’s a simple example to check the license. At the top of the index.html page, add a <script> tag referencing the markeplace.js file. Then use this code to check the license. Note that this pattern requires a callback, since that’s how the plugin model returns results. Passing the callback function name as a parameter each time it’s needed is an easy way to keep dependencies out of the marketplace.js file.

 <script>
   function checkLicense() {
       
       window.plugins.marketplace.checkLicense(licenseCallback);
   }
  
   function licenseCallback(isTrial) {
       if (isTrial) {
           licenseDiv.innerHTML = 'Trial mode, please buy me!';
       }
       else {
           licenseDiv.innerHTML = 'Thanks for buying!';
       }
   }
 </script>

This bit of HTML will interact with that JavaScript.

 <button onclick="checkLicense();">Check license</button>
 <div id="licenseDiv"></div>

Any time you need to check the licensing for your app, just use that pattern. In my next post, we’ll expand the marketplace Plugin with some other features. So get those apps out with trial mode and hook in your users!