How to implement a trial experience in an app for Windows Phone 8

Article
11/23/2015

[ This article is for Windows Phone 8 developers. If you’re developing for Windows 10, see the latest documentation. ]

This topic describes how to implement a trial experience in your Windows Phone app. The info in this topic applies primarily to apps designed to run on Windows Phone OS 7.1 or Windows Phone OS 7.0. If your app runs only on Windows Phone 8, consider instead using the Windows Runtime version of the LicenseInformation class, also supported for Windows Store apps, to implement a trial experience in your app. You can learn about this approach in the Windows Phone trial experience sample and in the topic Create a trial version of your app for the Windows Store.

The purpose of a trial experience is to give the user an opportunity to try your app before they commit to buying it. In a trial experience, you typically offer a limited version of your app, for example, by disabling features, by disabling levels in a game, or by setting a time limit on using the app. The limitation you choose for your app is entirely up to you. This topic demonstrates how to create a simple app that has a feature limit – some features are disabled – in trial mode. Determination of the mode in which the app is running is done using the LicenseInformation class. For more info about how to implement a trial experience, and a complete sample that further demonstrates the app described here, see Trial Applications Sample.

This topic contains the following sections.

Creating the app UI

In this section, you create the UI for demonstrating an app with a trial experience. This is a Windows Phone app. When the app starts, it checks the current license for the app. If the app has a trial license, it disables a feature. If the app has a full license, it enables all features. Real license information is available for an app only after it has been published to the Store. Therefore, to test the trial experience, we must simulate license detection. This will be done when the app is running in Debug mode by programmatically setting an IsTrial property in the app. After the app is published, the IsTrial property in the app will be set by examining the LicenseInformation.IsTrial property.

To create the app user interface

In Visual Studio, create a new project by selecting the File | New Project menu command.
The New Project window is displayed. Expand the Visual C# templates, and then select the Windows Phone templates.
Select the **Windows Phone App ** template. Fill in the Name with a name of your choice.
Click OK. A new project is created, and MainPage.xaml is opened in the Visual Studio designer window.

On MainPage.xaml, remove the XAML code for the Grid named “LayoutRoot” and replace it with the following code.

        <Grid x:Name="LayoutRoot" Background="Transparent">
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto"/>
            <RowDefinition Height="*"/>
        </Grid.RowDefinitions>

        <!--TitlePanel contains the name of the application and page title.-->
        <StackPanel x:Name="TitlePanel" Grid.Row="0" Margin="12,17,0,28">
            <TextBlock x:Name="ApplicationTitle" Text="Trial Application Experience" Style="{StaticResource PhoneTextNormalStyle}" Margin="5"/>
            <TextBlock x:Name="PageTitle" Text="main page" Style="{StaticResource PhoneTextTitle1Style}" Margin="5"/>
        </StackPanel>

        <!--ContentPanel - place additional content here-->
        <Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
            <Grid.RowDefinitions>
                <RowDefinition Height="200"/>
                <RowDefinition Height="Auto"/>
                <RowDefinition Height="Auto"/>
                <RowDefinition Height="Auto"/>
            </Grid.RowDefinitions>
            <StackPanel Grid.Row="0" Orientation="Horizontal"
                        HorizontalAlignment="Center" VerticalAlignment="Center">
                <TextBlock Text="License:" FontSize="{StaticResource PhoneFontSizeExtraLarge}" />
                <TextBlock x:Name="tbTrialStatus" FontSize="{StaticResource PhoneFontSizeExtraLarge}" />
            </StackPanel>
            <TextBlock Grid.Row="1" Text="My Application Features" HorizontalAlignment="Center"/>
            <StackPanel Grid.Row="2"  Orientation="Horizontal" HorizontalAlignment="Center">
                <Button Content=" A" Height="78" Width="100" x:Name="btnFeatureA" Click="btnFeatureA_Click"/>
                <Button Content=" B" Height="78" Width="100" x:Name="btnFeatureB" Click="btnFeatureB_Click"/>
                <Button Content=" C" Height="78" Width="100" x:Name="btnFeatureC" Click="btnFeatureC_Click"/>
            </StackPanel>
            <Button Grid.Row="3" x:Name="btnBuyApplication" Content="Buy the Application" Click="btnBuyApplication_Click" Height="78"/>
        </Grid>
    </Grid>

The preceding XAML code creates a simple user interface that looks like the following screenshot.

The app contains three buttons, each representing a feature of the app. The UI also contains status text showing the current license information and a button to buy the app. The preceding code and screenshot serve as a basic example to illustrate the core concepts of building a trial experience. The event handlers for each of the buttons will be defined in the following sections.

Checking for a trial license in your app

In this section, you use the LicenseInformation object to determine the current license of the app. Real license information is available for an app only after it has been published to the Store. Therefore, to test the trial experience, we must simulate license detection. This will be done when the app is running in Debug mode by programmatically setting an IsTrial property in the app. After the app is published, the IsTrial property in the app will be set by examining the LicenseInformation.IsTrial property.

To check for a trial license in a Direct3D app, check the IsTrial property of the LicenseInformation instance returned by the LicenseInformation property of the CurrentApp class.

To check for a trial license in your app

Open App.xaml.cs and add the following using directive to the top of the page.
```
using Microsoft.Phone.Marketplace;
```
In the App class, declare the following local static variable. The LicenseInformation class enables an app to determine if it is running under a trial license.
```
     private static LicenseInformation _licenseInfo = new LicenseInformation();
```
In the same App class in App.xaml.cs, add the following read-only property and local variable. This property is used to cache the license information while the app is running. The app uses the property whenever the current license information needs to be checked.
```
        private static bool _isTrial = true;
        public bool IsTrial
        {
            get
            {
                return _isTrial;
            }
        }
```

In the following sections, the license information will be checked in the Application_Launching and Application_Activated event handlers. Since this logic is used in two locations, we wrap it for convenience into its own method. In the App class located in App.xaml.cs, add the following method.

        /// <summary>
        /// Check the current license information for this application
        /// </summary>
        private void CheckLicense()
        {
            // When debugging, we want to simulate a trial mode experience. The following conditional allows us to set the _isTrial 
            // property to simulate trial mode being on or off. 
#if DEBUG
            string message = "This sample demonstrates the implementation of a trial mode in an application." +
                               "Press 'OK' to simulate trial mode. Press 'Cancel' to run the application in normal mode.";
            if (MessageBox.Show(message, "Debug Trial",
                 MessageBoxButton.OKCancel) == MessageBoxResult.OK)
            {
                _isTrial = true;
            }
            else
            {
                _isTrial = false;
            }
#else
            _isTrial = _licenseInfo.IsTrial();
#endif
        }

The preceding method consists of two code paths, depending on whether the app is run in Debug mode or not. In Debug mode, the code between the conditional compilation directive #if Debug and the #else directive is executed. The user is asked whether they would like to simulate trial mode. If the user selects OK, then the _isTrial variable is set to true; otherwise, it is set to false. If the app is built in release mode, the code between the #else and the #endif is executed and the _isTrial variable is set by examining the IsTrial property on the LicenseInformation object.

The license for the app should be checked whenever the app starts or resumes. This is done by checking the license information in the Application_Launching and Application_Activated event handlers. Replace the Application_Launching event handler in App.xaml.cs with the following code.
```
        private void Application_Launching(object sender, LaunchingEventArgs e)
        {
            CheckLicense();
        }
```

Replace the Application_Activated event handler in App.xaml.cs with the following code.

        private void Application_Activated(object sender, ActivatedEventArgs e)
        {
            CheckLicense();
        }

Enabling or disabling a feature based on the current license information

In this section, you use the information about the app’s current license to limit the app in trial mode. How the app is limited is your choice. In this example, the app is limited in trial mode by disabling a button on the UI that represents a feature of the app. A button is also made visible on the UI to enable the user to buy the app through the Store, by calling the Show method. Because this app has not been published to the Store, the call to Show will result in an error. This is expected behavior.

To enable or disable a feature based on the current app license information.

In the MainPage.xaml.cs code-behind file, add the following methods.

       protected override void OnNavigatedTo(System.Windows.Navigation.NavigationEventArgs e)
        {
            base.OnNavigatedTo(e);

            if ((Application.Current as App).IsTrial)
            {
                btnBuyApplication.Visibility = System.Windows.Visibility.Visible;
                btnFeatureC.IsEnabled = false;
                tbTrialStatus.Text = "Trial";
            }
            else
            {
                btnBuyApplication.Visibility = System.Windows.Visibility.Collapsed;
                btnFeatureC.IsEnabled = true;
                tbTrialStatus.Text = "Full";
            }
        }

        private void btnFeatureA_Click(object sender, RoutedEventArgs e)
        {
            MessageBox.Show("Feature A");
        }

        private void btnFeatureB_Click(object sender, RoutedEventArgs e)
        {
            MessageBox.Show("Feature B");
        }

        private void btnFeatureC_Click(object sender, RoutedEventArgs e)
        {
            MessageBox.Show("Feature C");
        }

In the preceding code, the OnNavigatedTo method is overridden to determine the current license information whenever the user navigates to this page. The IsTrial property of the App class, defined in the previous sections, is examined to determine whether the app is running in trial mode or running with a full license. If this property returns true, the app is running in trial mode. The btnFeatureC button is disabled to simulate disabling a feature when in trial mode. The btnBuyApplication button is also made visible so that the user has a way to initiate an app purchase. Finally, the license status is set on the tbTrialStatusTextBlock.

In the case where the IsTrial property is false, all features are enabled. The btnBuyApplication button is hidden, since the user has a full license of the app. Finally, the license status is set on the tbTrialStatusTextBlock. The three click events are used to show a message when the user clicks one of the feature buttons in the UI.

Prompting the user to buy the app

In this section, you use the MarketplaceDetailTask to bring the user to your app in the Store so that the user can buy the app.

To prompt the user to buy the app

Open MainPage.xaml.cs and add the following using directive to the top of the page.
```
using Microsoft.Phone.Tasks;
```

At the top of the MainPage class in the MainPage.xaml.cs code-behind file, add the following variable.

        // Declare the MarketplaceDetailTask object with page scope
        // so we can access it from event handlers.
        MarketplaceDetailTask _marketPlaceDetailTask = new MarketplaceDetailTask();

In the MainPage.xaml.cs code-behind file, add the following method.
```
        private void btnBuyApplication_Click(object sender, RoutedEventArgs e)
        {
            _marketPlaceDetailTask.Show();
        }
```
When the btnBuyApplication button is clicked on the UI, the preceding code will show the Store client app and display the details page for the specified product. The user will be able to buy the app. In this example, the app is not published to the Store. As a result, the _marketPlaceDetailTask.Show() call will result in an error being displayed. If this error has the error code 805a0941, then the call was successful and will operate correctly when the app is published. When your app is published, the Show will automatically detect your app’s unique ID and launch the correct details page in the Store client app.

Running the app

To run the app

On a device or emulator, run the app by selecting the Debug | Start Debuggingmenu command.

Note

The option to select trial mode simulation is available only when the app is run in debug mode. This is done to prevent trial mode simulation from running in the release build of the app and accidentally being published to the Store with this test feature enabled.

When the app starts, a message box is displayed. Click OK to simulate trial mode.
In the main page of the app observe that the License field is set to Trial and the Feature C button is disabled.
Click the Buy the Application button. An attempt is made to open the Store client app.
You will see an error dialog that looks like the following image. This indicates that the app successfully opened the Store client app. On a published app, this error will not occur and you will be brought to the details page of the app on the Store where you can purchase the app.
Click Close on the error dialog. The app will resume.
To run the app to simulate a full license, click Cancel on the MessageBox that appears in step two of this procedure. Alternatively, you can start the app by selecting the Debug | Start without Debuggingmenu command. In this mode, the Buy the Application button will be hidden and the Feature C button will be enabled.