Using in-app ratings with the RateBox native extension for Adobe AIR on iOS and Android

Getting good user ratings is a crucial part of your app’s success on iOS or Android--and reminding your most engaged users to give you a rating is one of the most effective ways to get them. This article covers techniques for increasing your mobile app store ratings with the RateBox In-App Ratings Extension for iOS and Android, which enables you to:

• Maximize downloads by getting five-star ratings from top users
• Smoothly launch the native rating page on the device's app store
• Enable automatic ratings with just a few lines of code
• Automatically track number of uses, days installed, or custom metrics
• Automatically detect when a new version is installed and ask for new ratings
• Receive events when the user completes or declines to rate the app
• Use one extension for both iOS and Android ratings

Before you can use RateBox for iOS apps, you'll need to retrieve your app’s Apple ID from itunesconnect.apple.com. This a unique nine-digit string of numbers assigned to your app by Apple; it is not the same as your application bundle ID from the AIR descriptor file.

1. Go to http://itunesconnect.apple.com and log in with your developer account credentials.
2. Select Manage Your Applications.
3. Locate and select your app. (If you have not yet registered your app in iTunes Connect, you can do so now.)
4. Copy your Apple ID from the App Information section. You'll need this ID to initialize the extension in ActionScript. Figure 1 shows the location of the iTunes App ID.

The next step is to add the com.milkmangames.nativeextensions.RateBox.ane library to your project. (If you are not using Flash Builder 4.6 and later or Flash Professional CS6 and later you’ll need to add the RateBoxAPI.swc library instead.)

In Flash Professional CS6:

1. Create a new project of the type AIR for iOS or AIR for Android.
2. Choose File > Publish Settings.
3. Click the wrench icon next to Script for ActionScript Settings.
4. Select the Library Path tab.
5. Click the Browse For Native Extension (ANE) File button and select the com.milkmangames.nativeextensions.RateBox.ane file.

In Flash Builder 4.6:

1. Go to Project Properties (right-click your project in Package Explorer and select Properties).
2. Select ActionScript Build Path and click the Native Extensions tab.
3. Click Add ANE and navigate to the com.milkmangames.nativeextensions.RateBox.ane file.

In FlashDevelop:

1. Copy the RateBoxAPI.swc file to your project folder.
2. In the explorer panel, right-click the SWC and select Add To Library.
3. Right-click the SWC file in the explorer panel again, select Options, and then select External Library.

The RateBox extension can be up and running in a few simple calls. See example/RateBoxExample.as for a full example.

Follow these steps to get started:

1. Import the API Classes:

2. Initialize the RateBox API as early on in your application as possible (in the main constructor function of your document class, or at the beginning of the first frame in Flash Professional). To set up the API, call the RateBox.create() method with your app’s Apple ID (see Getting your iTunes app Apple ID), the title of the rating prompt, and the message for the rating prompt as parameters.

Note: If you are supporting Android but not iOS, you can set the first parameter to an empty string ("" ).

3. You can check RateBox.isSupported() first, to ensure that the current platform is supported by RateBox (either iOS or Android):

4. For testing purposes, you can enable Test Mode with a call to RateBox.rateBox.useTestMode(). While in test mode, clicking the Rate Now button will send the user to rate an existing app (Adobe Photoshop Express), on the store. This can be useful for seeing the entire flow of events when your own app has not yet been published to The App Store or Google Play. Remember to remove the useTestMode() call before publishing your application!

5. Call the RateBox.rateBox.onLaunch() method to signal the extension each time your app has launched. Because mobile applications tend to stay running in the background indefinitely, you may want to call this function inside a listener for the flash.desktop.NativeApplication ACTIVATE event. This way, if the user sends your app to the background, then returns to it days later, it will count as a new launch:

By default, RateBox will display a prompt to the user after the app has been launched three times. RateBox automatically handles the user's preferences (if they rated the app already, choose to be reminded to rate later, or opt never to be asked again), and automatically detects when the app has been updated to a new version so it can reset its timer and request a new rating.

It can also track the days since the app was installed as well as custom in-app events to prompt a rating request. For instance, a custom event could be finishing a level in a game, and you could prompt the user to rate after they've finished a level 10 times.

The text displayed in the options buttons (Rate Now, Remind Me Later, and Don't Ask Again) can also be customized.

Setting custom options

The complete parameter list for RateBox.create() is as follows:

Table 1 explains each parameter.

Custom option examples

The following examples show different ways to customize the rating prompt display rules when initializing RateBox:

Setting custom app event triggers

If you set the minEventsTilPrompt parameter as described above, RateBox will track custom in-app events to prompt a rating.

The following example increments RateBox's internal counter of custom events. If the counter has been reached, the rating prompt will be displayed:

Listening for event callbacks

RateBox dispatches the ActionScript events RateBoxEvent.PROMPT_DISPLAYED when the rating dialog prompt has been displayed to the user. It dispatches RateBoxEvent.RATE_SELECTED, RateBoxEvent.LATER_SELECTED, or RateBoxEvent.NEVER_SELECTED when the user selects one of the button actions in the prompt dialog box.

If the device does not have an active Internet connection, RateBox will not display the prompt dialog box, as there will be no way to access the app store and apply the rating. In this case, a RateBoxEvent.NETWORK_UNAVAILABLE event will be dispatched.

The following example demonstrates setting listener functions for each of the RateBox events:

Handling rating prompts manually

The RateBox extension automatically handles tracking of installation time, launches, and custom events for ratings. However, you can also implement your own custom rating rules if you wish.

By default, RateBox will display prompts automatically when the event conditions are met. You can disable this functionality by calling the setAutoPrompt() function:

When autoPrompt is set to false, you can still check if RateBox's internal rating conditions have been met (number of days installed, number of launches, and so on) by calling areRatingConditionsMet():

You may determine if the current version has been rated yet using the didRateCurrentVersion() function. In conjunction with the showRatingPrompt() function, you may implement your own rules about when the rating prompt is displayed:

Finally, the internal rating tracker can be reset by calling resetConditions(). This will also cancel any user preferences, such as having clicked Don't Ask Again:

RateBox.rateBox.resetConditions();

In your application descriptor file, you need to specify the version of the AIR SDK you are using (3.1 or later) as well as a link to the extension.  If you’re deploying to Android, you’ll also need to update the Android Manifest Additions with some RateBox specific settings. For a working example, see example/app.xml.

1. Set your AIR SDK to 3.1 or higher in the app descriptor file:
   <application xmlns="http://ns.adobe.com/air/application/3.1">
2. Include a link to the extension in the descriptor:
   <extensions>
<extensionID>com.milkmangames.extensions.RateBox</extensionID>
</extensions>
3. Update your Android Manifest Additions (the INTERNET and ACCESS_NETWORK_STATE permissions are required):

If you're using Flash Builder 4.6 or later, or Flash Professional CS6 or later, and have added the RateBox extension library as described above, then you can compile as you usually do directly from Flash Builder or Flash Professional.

If not and you are building your app with the extension from the command line, then you'll need to specify the directory containing the com.milkmangames.extensions.RateBox.ane file.

Here is an example build command line:

Now that you’re app is ready to drive more user ratings on the App Store and Google Play, you can use the following links to explore other native extensions and tutorials from Milkman Games:

• Using the GameCenter Adobe AIR native extension for iOS
• Using the iAd Adobe AIR native extension for iOS
• Using the AdMob Adobe AIR native extension for Android
• Amazon In-App Purchase Adobe AIR Native Extension
• Facebook, Twitter and Mail Adobe AIR Native Extension
• App Rating Adobe AIR Native Extension
• iOS In-App Purchase Adobe AIR Native Extension
• Android In-App Purchase Adobe AIR Native Extension
• iAd Adobe AIR iOS Native Extension
• GameCenter iOS Adobe AIR Native Extension
• AdMob for Android Adobe AIR Native Extension