Spike: In-App Review implementation on Android

[MessiasLima]

Description

Investigate how to implement Google Play In-App Review in the Android target of Foliary. The goal is to understand the API, integration points, KMP expect/actuals strategy, and triggering criteria so that an implementation ticket can be created with clear specs.

Background

In-App Review allows users to rate and review the app without leaving it, increasing review volume and quality. Since Foliary is a KMP app, the Android-specific Google Play Review API needs to be integrated via Kotlin expect/actual declarations, keeping the common code unaware of platform details. Before implementing, we need to determine when and how to trigger the review prompt and how to structure the multiplatform integration.

Current Knowledge

• Foliary is a KMP app using Compose Multiplatform (Android, iOS, Desktop JVM)
• The app uses Orbit MVI, Koin DI, and Room persistence
• No in-app review or rating code exists in the codebase
• Google Play In-App Review API is part of play-core (com.google.android.play:review)
• iOS has its own review prompt mechanism (SKStoreReviewController in StoreKit)
• The project uses Gradle version catalogs for dependency management

Scope

In scope: Google Play In-App Review API integration, KMP expect/actual declarations for triggering a review prompt, triggering criteria (e.g. after N tasks completed, after N days of use, after celebration illustration shown), platform quirk: Google enforces a rate limit (~1 prompt per year per user), iOS App Store review prompt as a secondary consideration for the expect/actual shape.

Out of scope: implementing the UI for a review prompt, implementing the iOS review prompt, implementing desktop review prompts, analytics on review prompts.

Outcomes

• Document how to add the play-core review dependency to the Android source set
• Define the KMP expect/actual declarations needed to trigger a review prompt from common code
• Document triggering criteria and timing (when in the user journey to prompt)
• Document the Google Play rate-limit quirk and how it affects prompting strategy
• Define the integration point in the ViewModel or screen (e.g. after celebration illustration on Today screen)
• Create an implementation ticket based on spike findings