> For the complete documentation index, see [llms.txt](https://docs.amply.tools/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amply.tools/user-guide/rate-review-flows.md). # Rate & review flows The native app-store review prompt is limited and unforgiving: each store caps how often it can appear, and a badly-timed prompt can surface a frustrated user and a one-star review. This page covers how to gate that prompt behind a positive moment and an audience filter so the users who see it are the ones most likely to leave a five-star rating. **Use this when** you want more positive ratings and fewer negative ones — and you have an in-app moment that reliably signals the user is happy (a completed task, a milestone, a successful purchase). **Don't use this when** you have no way to detect a positive moment. Asking at session start or after a generic screen view hurts your rating more than it helps. ## The idea A naive Rate & Review campaign runs on every session and prompts anyone the store allows. You get ratings from whoever happens to be around — including users mid-frustration. A gated Rate & Review campaign only fires after a signal that the user is in a good state. That signal is just an event your app already tracks. You use it as the trigger, and you narrow the audience further with targeting rules. The result is fewer prompts, and the prompts that do fire land on happier users. The guiding principle: a store rating is expensive. Both Apple and Google limit how often the native sheet can appear, so every call is effectively a finite resource. Spend it on users who have already shown positive engagement. Never spend it on a user the moment they open the app for the first time. A common extension is to run a **sentiment check** in front of the native prompt: a custom in-app question that asks the user if they are enjoying the app. Only users who answer positively are eligible for the Rate & Review campaign. Negative responders are routed to an in-app feedback form instead of the public store listing. This keeps low-star feedback inside the product where it can be acted on, rather than on the store page where it hurts acquisition. See [custom-popups.md](/user-guide/custom-popups.md) for the front-end of that flow. ## Pick the positive-moment event Before touching the dashboard, decide what counts as a positive moment in your product. Good candidates: * A task the user came to the app to complete (an export, a transaction, a save). * A streak or milestone (seventh consecutive day, tenth item added). * A positive response to an in-app sentiment question. Bad candidates: * App launch / session start. * A screen view with no action. * Any event that also fires during errors or failed flows. The event must be tracked by the mobile SDK. If it isn't yet, ask engineering to add one `Amply.track(...)` call at the right spot. Name it something recognizable, for example `PositiveMoment`, `TaskCompleted`, or `PositiveRatingShared`. ## Worked example — positive-moment trigger A fitness app tracks `WorkoutCompleted` whenever a user finishes a session. The team decides any user who has completed at least three workouts in the app's history is a strong candidate for a five-star rating. * **Triggering event**: `WorkoutCompleted`. * **Repeat Rules**: on the third occurrence globally (not session-scoped). * **Frequency Limits**: one prompt per device, lifetime. * **Who**: app version is current, country is a launch market. Result: users who hit the workout milestone see the store prompt once, ever. Everyone else is invisible to the campaign. ## Create the campaign 1. Open **Campaigns** in the project sidebar and click **New campaign**. 2. Enter a name. Choose type **Rate & Review**. 3. **Who** — narrow the audience so the prompt lands on engaged users only. Typical conditions: * **App Version** — exclude users on older builds that have known bugs. * **Custom Property** (for example `subscription_status == "active"`) — only prompt users who have completed onboarding or paid. * **Install Date** — exclude brand-new installs (the store caps repeat prompts, so spending a prompt on a first-day user is risky). 4. **When** — set the **Triggering event** to the positive-moment event you picked. * Under **Repeat Rules**, set the campaign to fire only after the event has occurred enough times to be meaningful (for example, on the third `TaskCompleted`, not the first). * Under **Frequency Limits**, cap the campaign to one prompt per device across a long window. The store will not show the native sheet more often than its own policy allows, so burning attempts is wasteful. 5. **What** — Rate & Review campaigns do not need a deeplink URL. The SDK calls the native review API on both platforms. 6. Save as **Draft**, verify (see [testing-and-rollout.md](/user-guide/testing-and-rollout.md)), then move to **Active**. ## How delivery behaves on each platform The campaign asks the platform to show its native review sheet. The platform decides whether to actually display it. | Platform | Behavior | | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | iOS | Triggers the native iOS rate prompt (handled by the SDK). iOS throttles prompts per user per app, so not every call results in a visible sheet. | | Android | Calls the Play Store in-app review API. In Play Store-distributed release builds the sheet may appear. In debug or sideloaded builds the SDK shows a simulated dialog that does not post a review. | Because the store limits visibility, never design a flow that assumes the prompt definitely appeared. Treat it as best-effort. ## Measuring success Keep an eye on: * The count of campaign triggers in the campaign detail view. This counts matched evaluations, not confirmed native sheet displays — the store decides whether the sheet actually appears. * Your store rating over time (App Store Connect and Play Console both show weekly averages). * The share of low-star reviews. If a negative-feedback side-flow is in place, low-star store reviews should trend down. * The distribution of positive-moment event counts per user. If most users never reach the trigger, the event is too rare and the campaign will never fire for them. If every user hits it in the first session, the event is too cheap and the prompt will be wasted on people who haven't seen enough value yet. ## Variations * **Three-step flow** — custom sentiment popup, then Rate & Review for positives, in-app feedback deeplink for negatives. Most powerful; requires a custom popup and a feedback form in the app. See [custom-popups.md](/user-guide/custom-popups.md) for the popup side and [managing-deeplinks.md](/user-guide/managing-deeplinks.md) for the feedback deeplink. * **Single-event flow** — pick one strong positive event and gate directly on it. Minimal setup, good default. Start here if you don't yet have a sentiment popup built. * **Audience-only flow** — for apps without a clear positive moment, gate by `session.counter >= N` and a retention-indicating custom property. Weaker signal, still better than untargeted. ## Common pitfalls * **Prompting too early.** Firing on session 1 or session 2 burns the store's allowance on users who haven't experienced the product yet. Wait for a retention signal. * **Prompting everyone who crosses the event.** The event alone is not enough — combine it with an audience filter so churned or dormant users are excluded. * **Forgetting frequency limits.** Even a well-chosen event will fire repeatedly for power users. Cap to one prompt per long window per device. * **Testing on a debug build and assuming production works.** The Android Play Store in-app review API only works in Play-distributed release builds. A positive test on a debug build only tells you the campaign evaluated; it does not confirm a live sheet will appear. ## Maintenance Rate & Review campaigns are not set-and-forget. Review them quarterly: * Confirm the positive-moment event is still a strong signal. Products evolve; the event that correlated with happiness last year may not this year. * Check whether any low-star reviews are still citing issues that should have been caught by the audience filter (for example, users on an unsupported OS version). Tighten the audience if so. * If your app now has an in-app feedback form, upgrade the flow to the three-step variation so negatives never reach the store. ## Related * [Custom popups](/user-guide/custom-popups.md) — build the sentiment check that feeds this flow. * [Managing deeplinks](/user-guide/managing-deeplinks.md) — route low-rating users to an in-app feedback form. * [Campaign actions](/concepts/campaign-actions.md) — how the action types fit together. * [Campaigns](/user-guide/campaigns.md) — campaign structure reference. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.amply.tools/user-guide/rate-review-flows.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.