Demystifying the new Play In-App Review API

During the #11WeeksOfAndroid the new Play In-App Review API was announced. This was a long due functionality that the Play team made available via the Play Core library.

While most of the feedback has been positive, we have seen some concerns from developers who need to adapt their UI flow to the requirements of the new API. To address these concerns, I would like to explain some of the decisions taken and provide some further guidance to make the most of the API.

“Why is the API not providing any information?”

Given the criticality and potential for misuse of an API that would expose users’ reviews or even notify if the review panel was shown, the team has designed the API prioritising user privacy and experience.

While this might seem that it is making developers’ lives harder, I believe that it’s not the case. The API is simple to use (just two method calls!) and designed for the developers’ benefit, while also balancing users’ privacy and preventing the incentivising of unwanted behaviours. The important point is to know “when to use it”.

“Review panel comes out of the blue”

The API is NOT “randomly” showing the review panel. Instead, the developer decides the best place and moment to launch the review flow.

What is true, is that the API was designed (as explained above) to protect users. This is done by not providing information if the review was shown and by not always showing the review flow (see “quota”).

This prevents possible misuses, for example, apps enforcing users to rate them or misleading UIs that would only promote “5 stars” (see “When to request an in-app review”).

“Can I use the API for my “rate me” button”

As explained above, the API should NOT be triggered from a call-to-action (i.e “rate me” button) instead it should be triggered as part of the user flow.

Otherwise, the user might not see any action happening after clicking the button if the conditions for showing the review dialog were not met.

“My app does not have any “success” screen, so I cannot trigger the review”

There are plenty of other situations where launching the review would be appropriate. For example, after the user has used the app X times or for longer than Y days. The review flow could be launched after application starts, just make sure not to over-trigger it and continue with your user flow after the review completes.

“This behavior will cause users to rate my app poorly”

Some of the early adopters have shown that when placed in the right place, the API can help users, that would maybe never have rated the app otherwise, to write a review when asked.

At the same time, if the API is misused it could definitely have a counterproductive effect.

“Why a comment is required to review”

It’s only required when the user is part of the Internal Test Track. For production users a comment is optional.

Note: with Internal App Sharing the submit button is always disabled

“I can use some workaround to find if the review panel was shown”

Congrats! While a workaround might seem viable it’s still a workaround, and basing your production code on internal implementation details is dangerous. Plus it defeats the design purpose, which could backfire with negative effects.

“The API is unreliable and not working”

The API has strict requirements to work, as explained in the “Test in-app reviews” section. The most common mistakes are:

• Not using an app that is published to Google Play
• Using an account that never installed the app via Google Play or an account that already reviewed the app.
• The primary account (and the one that installed the app) is NOT selected when having multiple accounts in the device.

For more, check the troubleshooting section.

“I must know what the quotas are! How am I supposed to know how often to ask for review?”

Given the API design of not providing completion/result feedback, the quota mechanism is designed to help developers avoid the misuse of the API and over-triggering the review request. The exact quota is an implementation detail, and they are subject to change in the future.

Instead of trying to figure out the quota, the app should add its own logic (when/where is the best time to request for review) and rely on the API to launch the review when conditions apply.

So… what’s the best way to use the API?

There is no single way or “best way”, furthermore every app has different use cases and user base. Although, the following suggestions might help you:

• Ensure the user has experienced the app before launching the review flow.
• Launch the review flow after screen transitions. For example, after performing some action and subsequently bringing back the user to the “main” screen.
• Avoid calling the API after call-to-action buttons where users might not be expecting a dialog/panel to be shown.
• Do NOT block users when launching the review by pre-loading the review flow ahead of time (requestReviewFlow) and skipping the launch if the request was not loaded on time (check sample’s ReviewViewModel).
• Do NOT over-trigger the review (i.e every app launch). Even when pre-loaded it can add some small delay to the UI.

The PlayCoreKtx sample app shows some of the suggestions above in a simplified way, by showcasing a flashlight app that allows you to pick the flashlight background color.

• The ReviewViewModel is responsible to “pre-warm” the review to keep the ReviewInfo object ready and provide it if conditions for the review are met.
• PaletteFragment requests the ReviewViewModel to pre-warm the review once launched.
• After the user selects a background from the PaletteFragment, comes back to the main screen and turns off the flashlight, the MainFragment requests the ReviewViewModel for the ReviewInfo to launch it.

Note: To keep the sample simple it’s not persisting the last time the review was triggered and also it uses a simple logic that might be met many times. For a production app, a more complex logic should be used.

Hopefully, this post helps clarify some concepts and lets you implement the new In-app Review API.

For more or any questions follow me on Twitter @marxallski