Utilities | Store Review: Scripting

This section provides a guide to work with the Store Review scripting API.

You can access the Store Review API via the StoreReview class under the EasyMobile namespace.

Making Rating Request

To show the native standard review popup provided by iOS (10.3+) and Android, simply call the RequestRating method. Note that the actual display of the popup is controlled by the underlying platform (iOS and Android), therefore you should NOT trigger this method upon a call-to-action option (e.g. a button). Rather, your app should call this method automatically when it makes sense in the experience flow of the app, to maximize the effectiveness of the request.

On iOS 10.3 or newer, the actual display of the rating dialog is governed by App Store policy. When your app is still in sandbox/development mode, the dialog is always displayed for testing purpose. However, it won't be shown in an app that you distribute using TestFlight.

On Android, the display of review popup is controlled by Google Play In-App Review API.

// Show the rating dialog with default behavior
StoreReview.RequestRating();

iOS before 10.3

On iOS 10.3 onward or Android, we use system provided rating dialog and Google Play In-App Review API implementation. The APIs described below are therefore now marked as obsolete. They are here to maintain backward compatibility for iOS versions bellow 10.3, which look awfully dated now :)

On iOS older than 10.3, you can discard the default behavior of the rating dialog and provide your own implementation to suit your needs (again, on iOS 10.3 or newer we employ the native rating prompt whose behavior is governed by the system itself). This can be useful in cases when you want to perform additional tasks like recording the number of users who gave good ratings (maybe for analytics purpose). To do so, simply call the RequestRating method passing a callback in which the custom behavior is implemented. This callback takes as input an enum value representing the user action, which you can use to decide whatever action should be taken. Note that you can use the DisableRatingRequest method to prevent the rating dialog from being displayed in the future, if the user selects "Don't Ask Again" option. Also note that you can pass a null RatingDialogContent object to use the default content, otherwise create a new object as described in the Localized the Rating Dialog section above.

From the analytics point of view, it's worth noting that the rating given in the rating dialog on Android is merely a suggestion of how the user would rate the app. There's currently no reliable way to verify if it is the actual rating given on the app stores or not.

To check if the rating dialog has been disabled (because the user selected Don't Ask Again or already gave a rating):

// Check if the rating dialog has been disabled
bool isDisabled = StoreReview.IsRatingRequestDisabled();

To get the number of used and remaining requests in the current year:

// Get the number of requests used this year
int usedRequests = StoreReview.GetThisYearUsedRequests();

// Get the number of unused requests this year
int unusedRequests = StoreReview.GetThisYearRemainingRequests();

To get the timestamp of the last request:

// Get the time when the last rating popup is shown
DateTime lastTime = StoreReview.GetLastRequestTimestamp();

To check if it's eligible to show the rating dialog (which means it hasn't been disabled and all display constraints are satisfied):

// Check if it's eligible to show the rating dialog and then show it
if (StoreReview.CanRequestRating())
{
    StoreReview.RequestRating();
}

// Show rating dialog with a callback for custom behavior
// Passing null for the RatingDialogContent parameter to use the default content
StoreReview.RequestRating(null, RatingCallback);

// The rating callback
private void RatingCallback(StoreReview.UserAction action)
{
    switch (action)
    {
        case StoreReview.UserAction.Refuse:
            // Don't ask again. Disable the rating dialog
            // to prevent it from being shown in the future.
            StoreReview.DisableRatingRequest();
            break;
        case StoreReview.UserAction.Postpone:
            // User selects Not Now/Cancel button.
            // The dialog automatically closes.
            break;
        case StoreReview.UserAction.Feedback:
            // Bad rating, user opts to send feedback email.
            break;
        case StoreReview.UserAction.Rate:
            // Good rating, user wants to rate.
            break;
    }
}

Localizing Rating Dialog (iOS before 10.3)

To localize the content of the rating dialog, simply create a new RatingDialogContent to hold the translated texts (which you may obtain from a standard localization plugin), and pass it to the RequestRating method.

// Create a RatingDialogContent object to hold the translated content of the dialog
var localized = new RatingDialogContent(
            YOUR_LOCALIZED_TITLE + RatingDialogContent.PRODUCT_NAME_PLACEHOLDER,
            YOUR_LOCALIZED_MESSAGE + RatingDialogContent.PRODUCT_NAME_PLACEHOLDER + "?",
            YOUR_LOCALIZED_LOW_RATING_MESSAGE,
            YOUR_LOCALIZED_HIGH_RATING_MESSAGE,
            YOUR_LOCALIZED_POSTPONE_BUTTON_LABEL,
            YOUR_LOCALIZED_REFUSE_BUTTON_LABEL,
            YOUR_LOCALIZED_RATE_BUTTON_LABEL,
            YOUR_LOCALIZED_CANCEL_BUTTON_LABEL,
            YOUR_LOCALIZED_FEEDBACK_BUTTON_LABEL
        );

// Show the rating popup with the localized texts
StoreReview.RequestRating(localized);

Any instance of RatingDialogContent.PRODUCT_NAME_PLACEHOLDER (literal value "$PRODUCT_NAME") will be automatically replaced by the actual product name (given in PlayerSettings) by the RequestRating method.