Integration quickstart
Get PromptSurge running in your app in under a day.
Working with Claude, ChatGPT, Gemini or Grok: hand the integration to your AI assistant.
Prerequisites
- Android API level 24+
- A PromptSurge account - sign up free
- An API key from the admin panel
1. Install the SDK
Add JitPack to your root settings.gradle.kts:
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven { url = uri("https://jitpack.io") }
}
}Then add the SDK to your app's build.gradle.kts:
dependencies {
implementation("com.github.PromptSurge-SDK:sdk-android:1.3.1")
}Sync Gradle. No additional permissions are required in AndroidManifest.xml.
2. Initialize
Initialize once, early in your Application.onCreate():
import com.promptsurge.sdk.PromptSurge
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
PromptSurge.initialize(this, "ps_live_your_key_here")
}
}Store your API key in local.properties or BuildConfig - never commit it to source control.
3. Trigger a prompt
Call requestReview() at a natural win moment - after a user completes a level, finishes an import, or achieves a milestone:
// In an Activity (AppCompatActivity works)
PromptSurge.requestReview(this)
// Or from a Fragment
PromptSurge.requestReview(requireActivity())The SDK handles all eligibility checks automatically:
- 90-day cooldown after the pre-prompt is shown
- 7-day cooldown after a dismiss
- 10% holdout group silently skipped for measuring lift
- Server-side billing limit - when your plan's monthly impression quota is reached the native review API is called directly until the quota resets
- Store-limit guard (Android SDK 1.2.0 and later) - no pre-prompt within 30 days of the SDK's last request for Play's review card, which Play's quota would likely keep hidden
- Falls back to a bundled English prompt if the API is unreachable
4. Opt-out support
Expose an opt-out option in your privacy settings:
// Opt the user out - persists across restarts, stops all SDK activity
PromptSurge.optOut(context)
// Re-enable if the user changes their mind
PromptSurge.optIn(context)API reference
| Method | Description |
|---|---|
| initialize(context, apiKey) | Initialize the SDK. Call once in Application.onCreate(). |
| initialize(context, apiKey, verifyToken) | Same, plus the one-time app-ownership token from the console (Verify Ownership). SDK 1.1.0 and later; remove it once the console shows the app as verified. |
| setLogLevel(level) | Logging verbosity: NONE, ERROR, WARN (default), INFO or DEBUG. Use INFO while testing to see why a prompt did or did not show. |
| requestReview(activity) | Show the pre-prompt if eligibility checks pass. Launches Play review on confirm. |
| optOut(context) | Permanently suppress all SDK activity for this device. |
| optIn(context) | Re-enable SDK activity (if user opts back in). |
| setLocaleOverride(locale?) | Override the device locale used to fetch prompt copy. Pass null to clear. |
| clearRateLimitForTesting() | Reset cooldown timestamps. Debug builds only. |
Nothing is showing - FAQ
The pre-prompt is suppressed far more often than it fails, and a suppressed pre-prompt still fires the native review sheet where the platform allows it. These are the four reads that come up most.
I integrated the SDK and no pre-prompt ever appears. Is it broken?+
Almost always no - it is the warm-up phase, and it is the single most common wrong read of a correct integration. A brand-new app shows no pre-prompt at all until it has recorded 50 distinct devices firing a native review request. Until then every requestReview() fires the native store review sheet directly, which is what builds the baseline the whole product measures lift against. The default mode is once - one warm-up for the app's lifetime, not per release.
A test device will never reach 50 on its own, so this is the expected state during an integration rather than a bug. Turn it off for an app from its overview page in the dashboard (Warm-up control), or leave it on and watch it happen with the log level turned up.
Why does the SDK print nothing about why it stayed quiet?+
By design, and it is a deliberate trade rather than an oversight. Errors and warnings always print - a rejected API key, a spent monthly impression cap, an app deleted in the admin panel. But the four reasons a correctly wired integration shows nothing - warm-up, the holdout group, the two cooldowns and an opted-out device - are logged at info level, and the default is WARN. We keep the default quiet so the SDK does not write to every integrator's console forever on the happy path. Turn it up while integrating:
PromptSurge.setLogLevel(PromptSurge.LogLevel.INFO)Then filter your log output for [PromptSurge]. The SDK names the exact check it hit. The full table, in the order the checks run, is in the README for your platform.
The dialog appeared once and has never come back.+
Cooldowns, stored on the device: 90 days after a pre-prompt is shown, 7 days after one is dismissed. The cooldown is recorded when the dialog actually appears, not when it is requested. At info level the SDK prints how long ago it was and what the cooldown is.
It works on one device and never on another, with the same build.+
10% of devices are placed in a silent holdout group for their lifetime, so the lift measurement has a control. That assignment is persisted per device, so a device in the holdout stays in it. Try another device - or turn the log level up, where the holdout branch says so by name.
Store guidelines and the pre-prompt
PromptSurge shows a short dialog of your own before the store's review sheet, and its confirm button requests that sheet. Apple and Google both write about this pattern. This section quotes what they say, with links, and states what PromptSurge does about each point.
What the stores say
- Apple, StoreKit documentation. The requestReview(in:) reference says not to call it “in response to a button tap or other user action”, because the method may not present the sheet: the system decides, and shows it to a user at most three times in 365 days (Requesting App Store reviews).
- Google, In-App Review guide. The guide says an app “should not have a call-to-action option (such as a button) to trigger the API”, because the user may already have hit Play's quota and the card would not appear. It also says an app “shouldn't ask the user any questions” before or while presenting the card, naming opinion questions and predictive ones such as asking for five stars.
- App Store Review Guideline 5.6.1. Guideline 5.6.1 asks apps to “use the provided API to prompt users to review your app” and ends “we will disallow custom review prompts”. We read that as custom rating screens, a dialog that collects stars or a review itself instead of Apple's sheet. That reading is ours, not Apple's.
What PromptSurge does about each point
- Statements, not questions. The default copy is “A quick favor” / “A short review helps other people discover apps like this.”, and the built-in AI writes statements too. The dashboard warns you when your own title or body contains a question or reads like a satisfaction question (“Enjoying the app?”). It warns and saves; your copy is never blocked.
- The store's own sheet, unchanged. Sure requests StoreKit's review sheet on iOS (current SDK versions use
AppStore.requestReview(in:)on iOS 16 and later,SKStoreReviewControllerbefore that; the Unity SDK usesSKStoreReviewController) and Google Play's In-App Review flow on Android. PromptSurge never draws stars, never collects a rating or review itself and never puts anything on top of the store's sheet; its own dialog has closed before the sheet opens. - “Not now” requests nothing. Declining closes the dialog, starts a cooldown and uses none of the store's quota.
- Quota-aware suppression, so a yes is not met by nothing. From iOS SDK 1.3.0, Android SDK 1.2.0 and Unity SDK 1.3.0 (released 2026-10-19), the pre-prompt is not shown on an iOS device once the SDK has requested Apple's sheet there three times in the last 365 days, Apple's published limit, and not on an Android device within 30 days of the SDK's last request for Play's card. Google does not publish its quota; 30 days follows its own example of a short period (“less than a month”). The Unity SDK applies the rule of the platform it runs on. This lowers the chance that a tap on Sure shows nothing. It cannot remove it: the store still decides, and it can also stay silent for a user who has already rated.
- Never filters by sentiment. Every user who sees the pre-prompt is asked the same way, whatever they think of the app, and nothing routes unhappy users anywhere else.
The decision is the store's
These are guidelines the stores interpret, and whether an app passes review is the store's decision, not ours. Both stores advise against a button that triggers their review sheet, and a pre-prompt's confirm button is such a button. PromptSurge works on the reason they give, a tap met by nothing, but the button is still there. Weigh that for your app before you ship.
Tell App Review about it
We recommend describing the pre-prompt to Apple: in App Store Connect, on the version you submit, under App Review Information, in the Notes field. A suggested note, with [action] replaced by your review moment and the button names changed if you changed them:
After a user completes [action], the app shows a short request to leave a review. Tapping Sure requests the system rating sheet (SKStoreReviewController / AppStore.requestReview); tapping Not now closes it. The app never asks how the user feels and never collects a rating itself.
The warm-up and the control group are measurement features. While an app is in its warm-up, and on control-group devices, the native sheet is requested without the pre-prompt, so a reviewer may not see the dialog. That is a side effect, not a way to keep the pre-prompt out of review: describe it in the note either way, so the reviewer knows what your users will see.
Need help?
Email us at hello@promptsurge.me or open the dashboard to manage your prompts and view metrics.
Open dashboard →