PromptSurge
Empezar

Integration quickstart

Get PromptSurge running in your app in under a day.

Prerequisites

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.1.0")
}

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:

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

MethodDescription
initialize(context, apiKey)Initialize the SDK. Call once in Application.onCreate().
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.

Apple / Google compliance

PromptSurge is designed from the ground up to comply with both Apple App Store Review Guideline 5.6.1 and Google Play's in-app review policy:

Need help?

Email us at [email protected] or open the dashboard to manage your prompts and view metrics.

Open dashboard →