# PromptSurge: integration guide for AI coding assistants > PromptSurge is an in-app review prompt SDK for Android, iOS and Unity. The app calls requestReview at a moment the developer chooses. The SDK shows a short message (the pre-prompt) that asks for a review; a yes opens the store's own rating sheet, a not-now closes the message and nothing else happens. The message, its languages and its look are set in a web console and reach devices without an app update. This file is written for an AI coding assistant that has been asked to add PromptSurge to a project. Follow it step by step. Human-readable docs: https://promptsurge.me/en/docs ## What only the human can do You cannot do these. Ask the developer to do them and wait: 1. Create an account at https://admin.promptsurge.me/signup (free plan, no credit card). 2. Create an app in the console and copy its API key. The key starts with ps_live_ and is shown only once. 3. In the console, open Pre-prompt, pick a message for the app's category and press Go live. Until they do, users see a built-in English default. Ask the developer for the API key. Put it wherever this project already keeps configuration that must stay out of source control (local.properties or BuildConfig on Android, an .xcconfig on iOS, a ScriptableObject or config asset that is git-ignored on Unity). Do not commit it. ## Where to call requestReview This is the one decision that matters, and it is yours to propose and the developer's to approve. - Call it right after the user has finished something successfully: a completed level, a saved or exported file, a finished session, a delivered order. - Call it from ONE place to start with. - Never at app launch, never during a task, never after an error. - Never behind a "Rate us" button or menu item. Apple's and Google's own documentation advise against triggering the rating sheet from a button, because the store may decide not to show it. - Never add your own dialog before it, and never ask the user how they feel about the app first. PromptSurge's message is the only step before the store's sheet. - You do not need to add cooldown or frequency logic. It is built in (see Behaviour). ## Android (Kotlin or Java) Requirements: Android API level 24 or higher. requestReview needs a FragmentActivity (AppCompatActivity is one). 1. Add JitPack to the root settings.gradle.kts: ```kotlin dependencyResolutionManagement { repositories { google() mavenCentral() maven { url = uri("https://jitpack.io") } } } ``` 2. Add the dependency to the app module's build.gradle.kts: ```kotlin dependencies { implementation("com.github.PromptSurge-SDK:sdk-android:1.3.1") } ``` No manifest permission has to be added by hand. 3. Initialize once in Application.onCreate(): ```kotlin import com.promptsurge.sdk.PromptSurge class MyApp : Application() { override fun onCreate() { super.onCreate() PromptSurge.initialize(this, "ps_live_your_key_here") } } ``` If the project has no Application subclass, create one and register it with android:name in AndroidManifest.xml. 4. Ask for the review at one success moment: ```kotlin PromptSurge.requestReview(this) // in an Activity PromptSurge.requestReview(requireActivity()) // in a Fragment ``` 5. While testing, in debug builds only: ```kotlin PromptSurge.setLogLevel(PromptSurge.LogLevel.INFO) ``` Other public calls: optOut(context), optIn(context), setLocaleOverride(locale), clearRateLimitForTesting() (debug builds only, never ship a call to it). initialize also takes an optional third argument verifyToken, used once to prove app ownership (console: Verify Ownership). ## iOS (Swift) Requirements: iOS 14 or higher, Xcode 14 or higher. 1. Add the Swift package. In Xcode: File, Add Package Dependencies, paste https://github.com/PromptSurge-SDK/sdk-ios and add the PromptSurge product to the app target. Or in Package.swift: ```swift dependencies: [ .package(url: "https://github.com/PromptSurge-SDK/sdk-ios.git", from: "1.4.0"), ], targets: [ .target(name: "YourTarget", dependencies: ["PromptSurge"]), ] ``` 2. Initialize once at launch (SwiftUI App.init or UIKit application(_:didFinishLaunchingWithOptions:)): ```swift import PromptSurge PromptSurge.initialize(apiKey: "ps_live_your_key_here") PromptSurge.prefetch() // optional: loads the message early so the dialog opens without a wait ``` 3. Ask for the review at one success moment, passing the view controller on screen: ```swift PromptSurge.requestReview(in: self) ``` In SwiftUI, pass the root view controller of the active UIWindowScene. 4. While testing, in debug builds only: ```swift PromptSurge.setLogLevel(.info) ``` Other public calls: optOut(), optIn(), isOptedOut. initialize also takes an optional verifyToken argument, used once to prove app ownership (console: Verify Ownership). On confirm the SDK requests StoreKit's review sheet (AppStore.requestReview(in:) on iOS 16 and later, SKStoreReviewController before that). ## Unity (C#) Requirements: Unity 2022.3 LTS or later. Android builds: Play Store distribution. iOS builds: iOS 14 or higher. 1. Add the package. Window, Package Manager, +, Add package from git URL: ``` https://github.com/PromptSurge-SDK/sdk-unity.git#v1.4.0 ``` Or in Packages/manifest.json: ```json { "dependencies": { "me.promptsurge.sdk-unity": "https://github.com/PromptSurge-SDK/sdk-unity.git#v1.4.0" } } ``` 2. Android only: the SDK uses Google Play's In-App Review library. With External Dependency Manager (EDM4U) the bundled Editor/PromptSurgeDependencies.xml is resolved automatically. Without EDM4U add this to Assets/Plugins/Android/mainTemplate.gradle: ```groovy dependencies { implementation 'com.google.android.play:review:2.0.1' } ``` 3. Initialize once in a persistent object: ```csharp using PromptSurgeSDK; public class GameManager : MonoBehaviour { void Start() { PromptSurge.Initialize("ps_live_your_key_here"); PromptSurge.Prefetch(); // optional: loads the message early } } ``` 4. Ask for the review at one success moment: ```csharp PromptSurge.RequestReview(); ``` It does nothing in the Unity Editor. Test on a device. 5. While testing, in development builds only: ```csharp PromptSurge.SetLogLevel(LogLevel.Info); ``` Other public calls: OptOut(), OptIn(), IsOptedOut, SetRateLimitBypass(bool) (testing only, never ship it switched on). Initialize also takes an optional named argument verifyToken, used once to prove app ownership (console: Verify Ownership). ## Behaviour to expect (so you can explain it instead of "fixing" it) - Warm-up: for the first 50 devices of an app no message is shown. requestReview goes straight to the store's sheet. This builds the baseline the dashboard compares against. A developer testing on one device will therefore usually see no PromptSurge dialog at first. That is expected, not a bug. With the log level at info the SDK says which path it took. - Control group: about 10% of devices never see the message and always go straight to the store's sheet. - Cooldowns: after the message was shown, 90 days pass before it can show again on that device; after a not-now, 7 days. - Store limits: current SDK versions do not show the message when the store's own limits would likely keep its sheet hidden (iOS: 3 requests in 365 days; Android: within 30 days of the last request). - The store decides whether its sheet appears. A yes requests it; the store may still not show it, for example shortly after a previous request. Each store documents how its sheet behaves in test builds. - Plan limit: when the app's monthly message quota is used up, requestReview goes straight to the store's sheet until the quota resets. - Offline: the SDK falls back to cached copy, then to a built-in English message. - Unity: nothing happens in the Editor. ## How to verify your work 1. The project builds. 2. With the log level at info, launching the app logs the SDK's initialization. 3. Reaching the success moment logs the path taken (message shown, warm-up, control group, cooldown or store limit). 4. In the console, the app's Events page lists an initialize event within a minute or two, and the dashboard's SDK status switches to active. Do not ship calls to clearRateLimitForTesting (Android) or SetRateLimitBypass(true) (Unity), and do not leave the log level at info in release builds. ## What to tell the developer when you are done - Which file and function calls requestReview, and why that moment. - That the first 50 devices see only the store's sheet (warm-up), so "no dialog" on a test device is expected. - That the message, its languages and its look are edited in the console under Pre-prompt, with no app update. - That App Review should be told about the pre-prompt in the review notes; the wording to copy is at https://promptsurge.me/en/docs#store-guidelines. How a store reviews an app is that store's decision. - That the console's Overview compares reviews before and with the pre-prompt once reviews come in. ## Links - Docs: https://promptsurge.me/en/docs - What Apple and Google write about review prompts: https://promptsurge.me/en/docs#store-guidelines - Pricing: https://promptsurge.me/en/pricing - Site summary: https://promptsurge.me/llms.txt - Android SDK source: https://github.com/PromptSurge-SDK/sdk-android - iOS SDK source: https://github.com/PromptSurge-SDK/sdk-ios - Unity SDK source: https://github.com/PromptSurge-SDK/sdk-unity - Support: hello@promptsurge.me