Requirements
Prerequisite knowledge
Experience building games for iOS or Android with Flash Professional or Flash Builder and Adobe AIR will help you make the most of this article.
Required products
Flash Builder (Download trial)
Adobe Animate CC
Adobe AIR SDK
Additional required other products
Milkman Games RateBox Native Extension
User level
Intermediate

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

 
Getting your iTunes app Apple ID

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.
Figure 1. Identifying your app’s Apple ID.
Figure 1. Identifying your app’s Apple ID.
 

 
Including the RateBox API Library

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.

 
Getting started with the API

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:
import com.milkmangames.nativeextensions.*; import com.milkmangames.nativeextensions.events.*;
  1. 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 ("" ).
 
  1. You can check RateBox.isSupported() first, to ensure that the current platform is supported by RateBox (either iOS or Android):
if (RateBox.isSupported()) { RateBox.create("123456789","Rate My App","If you like this app, please rate it 5 stars!"); }
  1. 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!
// causes rating prompts to redirect to an existing example app on // the store, because your own app has not yet been published. Remember to // remove this line when you're doing testing and ready to publish! RateBox.rateBox.useTestMode();
  1. 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:
// listen for 'activate' events flash.desktop.NativeApplication.nativeApplication.addEventListener(Event.ACTIVATE,onActivate); function onActivate(e:Event):void { RateBox.rateBox.onLaunch(); }

 
Advanced options and custom events

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:
 
RateBox.create(iosAppId, title, message, rateNowLabel, declineLabel, neverAgainlabel, minLaunchesTilPrompt, minEventsTilPrompt, minDaysTilPrompt, coolDownDays);
Table 1 explains each parameter.
 
Parameter Description Default Value
iosAppId (String) The app’s Apple ID from iTunes Connect (Required)
title (String) The title that shows at the top of the rating prompt dialog box. (Required)
message (String) The message to display to the user in the rating prompt dialog box. (Required)
rateNowLabel (String) The label for the Rate Now button that will appear in the rating prompt dialog box. "Rate Now"
declineLabel (String) The label for the Not Now button that will appear in the rating prompt dialog box. "Not Now"
neverAgainLabel (String) The label for the Don't Ask Again button that will appear in the rating prompt dialog box. " Don't ask again"
Parameter Description Default Value
minLaunchesTilPrompt (int) The number of times the app must be launched as counted by RateBox.rateBox.onLaunch() before the user will be prompted for a rating. 3
minEventsTilPrompt (int) The number of times a custom event must be triggered with RateBox.rateBox.incrementEventCount() before the user will be prompted for a rating.
(The default value of 0 means that custom events are not used.)
0
minDaysTilPrompt (int) The number of days the app must be installed for before the user will be prompted for a rating.
(The default value of 0 means that days installed is not used.)
0
coolDownDays (int) The number of days the extension will wait before asking the user to rate again, if they choose "Not Now" in the dialog box. 1
 
Custom option examples
The following examples show different ways to customize the rating prompt display rules when initializing RateBox:
 
// The following example will display the RateBox after a custom // event has been triggered 3 times. RateBox.create("123456789","Rate This App","If you like this app, please rate it!","Rate Now","Ask Me Later","Don't ask again",0,3,0); // this would show the rating prompt after the app has been // installed for 3 days: RateBox.create("123456789","Rate This App","If you like this app, please rate it!","Rate Now","Ask Me Later","Don't ask again",0,0,3); // this would show the rate prompt after the app has been launched 3 times: RateBox.create("123456789","Rate This App","If you like this app, please rate it!","Rate Now","Ask Me Later","Don't ask again",3,0,0); // you can mix and match these values if you want. this would show the rate // box if the app has been launched at least 3 times, and been installed for // 5 days. RateBox.create("123456789","Rate This App","If you like this app, please rate it!","Rate Now","Ask Me Later","Don't ask again",3,0,5);
 
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:
 
function onFinishedLevel():void { RateBox.rateBox.incrementEventCount(); }
 
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:
 
// optional event listeners- dispatched when the user has clicked // a button in the rating dialogRateBox.rateBox.addEventListener(RateBoxEvent.RATE_SELECTED,onDidRate); RateBox.rateBox.addEventListener(RateBoxEvent.LATER_SELECTED,onDeclinedToRate); RateBox.rateBox.addEventListener(RateBoxEvent.NEVER_SELECTED,onWillNeverRate); // optional event listeners- dispatched when the rating prompt is shown, // or can't be shown due to a network issue RateBox.rateBox.addEventListener(RateBoxEvent.NETWORK_UNAVAILABLE,onRateNotDisplayed); RateBox.rateBox.addEventListener(RateBoxEvent.PROMPT_DISPLAYED,onRateDisplayed);
 
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:
 
// prevent RateBox from showing the rating prompt dialog automatically RateBox.rateBox.setAutoPrompt(false);
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():
 
if(RateBox.rateBox.areRatingConditionsMet()) { RateBox.rateBox.showRatingPrompt("Rate My App","Please Rate this App!!"); }
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:
 
if (!RateBox.rateBox.didRateCurrentVersion()) { RateBox.rateBox.showRatingPrompt("Rate My App", "Please rate this if you like it!"); }
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();
 

 
Updating your application descriptor file

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):
     
<android> <manifestAdditions><![CDATA[ <manifest android:installLocation="auto"> <uses-permission android:name="android.permission.INTERNET"/> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/> </manifest> ]]></manifestAdditions> </android>

 
Building the application

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:
 
[PATH_TO_AIR_SDK]\bin\adt -package -target ipa-test-interpreter -storetype pkcs12 –keystore [YOUR_KEYSTORE_FILE] -storepass [YOUR_PASSWORD] -provisioning-profile [YOUR_MOBILEPROVISION_FILE] ratebox.ipa app.xml gcexample.swf -extdir [DIRECTORY_CONTAINING_ANE_FILE]

 
Where to go from here

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: