Skip to content
Docs
Main site, archipelago.banuacoder.com
Back to archipelago.banuacoder.com

Feature SDKs (Free)

rating_review_sdk Free ​

Tier
Freeversion 2.0.4
Command
archipelago generate rating_review_sdk
Generates
  • features/rating_review/rating_review_api
  • features/rating_review/rating_review_impl
Generates first
storage_sdk, package_info_providerwhen needed and missing, so there is nothing to install first

In-app rating and review SDK. Wraps in_app_review with smart-prompting heuristics (session/key-event thresholds, cooldown, per-version gate). Thresholds are configured at runtime via RatingPromptConfig, not at generation time.

Variables ​

This brick has no generation-time variables. All prompting behaviour is configured at runtime via RatingPromptConfig.

Prerequisites ​

rating_review_impl persists session/key-event counters and prompt history through storage_sdk_api's StorageProvider, and consumes PackageInfo from package_info_provider's single global registration, instead of registering either itself (two features doing that independently crashed GetIt with a duplicate-registration error).

  • storage_sdk — self-generated automatically if not already installed (since 1.4.0), no manual step.
  • package_info_provider — self-generated automatically if not already installed (since 1.4.2), no manual step.

Usage ​

Interactive ​

bash
archipelago generate rating_review_sdk

Non-interactive (CI) ​

bash
archipelago generate rating_review_sdk --config my_config.json

Generated Structure ​

text
features/
└── rating_review/
    ├── rating_review_api/
    │   └── lib/src/
    │       └── models/
    └── rating_review_impl/
        └── lib/src/
            └── di/

Smart-Prompting Gates ​

The SDK evaluates conditions in this order before showing the prompt:

  1. Platform availability — InAppReview.isAvailable() must return true
  2. Session threshold — user must have completed minSessions app launches
  3. Key event threshold — user must have triggered minKeyEvents positive moments
  4. Cooldown period — at least cooldownDays must have passed since the last prompt
  5. Per-version gate — if askOncePerVersion is true, prompt is shown at most once per app version string

Runtime Configuration ​

Override the default thresholds by providing a RatingPromptConfig in your DI module before RatingReviewImplPackageModule:

dart
@module
abstract class AppDIModule {
  @lazySingleton
  RatingPromptConfig get ratingPromptConfig => const RatingPromptConfig(
    minSessions: 3,
    minKeyEvents: 2,
    cooldownDays: 30,
    askOncePerVersion: true,
    iosAppStoreId: 'YOUR_APP_STORE_ID',
  );
}

Integration ​

dart
final ratingSDK = getIt<RatingReviewSDK>();

// Once per app launch (post-launch hook or app shell initState):
await ratingSDK.recordSession();

// After a positive user moment:
await ratingSDK.recordKeyEvent('checkout_completed');

// At an appropriate UX moment (e.g. success screen):
if (await ratingSDK.shouldRequestReview()) {
  await ratingSDK.requestReview();
}

Analytics Integration ​

Use evaluatePromptDecision() to get structured decision results for telemetry without triggering the prompt:

dart
final decision = await ratingSDK.evaluatePromptDecision();
switch (decision) {
  case RatingPromptDecisionShow():
    await ratingSDK.requestReview();
  case RatingPromptDecisionSkip(:final reason):
    analytics.track('rating_prompt_skipped', {'reason': reason.name});
}

reset() clears all persisted state (session counter, key-event tally, last-prompt timestamp and version) — useful for tests or an explicit "ask me again later" flow:

dart
await ratingSDK.reset();

DI and wiring notes ​

rating_review_impl/pubspec.yaml declares its archipelago: di_modules block for monorepo_toolkit generate host-registry:

yaml
archipelago:
  di_modules:
    - class: RatingReviewImplPackageModule
      depends_on:
        - storage_sdk_shared_preferences
        - package_info_provider

RatingReviewSDKImpl is registered as a lazy @LazySingleton(as: RatingReviewSDK) (since 2.0.0): it does no startup work, so it is built the first time something resolves RatingReviewSDK. It requests its own 'rating_review' namespace from StorageProvider — non-secure, StorageScope.application (the default), so its counters are not swept by a logout-clear coordinator.

Dependencies ​

  • storage_sdk_api — self-generated automatically if not already installed
  • package_info_provider — self-generated automatically if not already installed
  • in_app_review — wraps the native InAppReview/SKStoreReviewRequestAPI plugin

Platform Setup ​

iOS ​

Set iosAppStoreId in RatingPromptConfig so openStoreListing() works correctly. Without it, openStoreListing() is a no-op on iOS. No Info.plist changes are required.

Android ​

The In-App Review API requires your app to be available on the Play Store (internal testing track is sufficient). In debug builds, InAppReview.isAvailable() returns false — the SDK silently skips all prompts, which is the expected behaviour.

Known Limitations ​

  • There is deliberately no "already rated" skip reason — neither Apple's nor Google's review API exposes whether the user actually submitted a rating. The withinCooldown + alreadyShownThisVersion gates approximate the same effect instead.
  • requestReview()'s return value reflects whether the SDK decided to call the plugin, not whether the user actually saw or completed the native dialog — both platforms may silently throttle it regardless.

Changelog ​

Run archipelago brick info rating_review_sdk to see the latest published version. Enterprise customers can read the full CHANGELOG.md in the brick source repository.