feat: implement in-app review prompt and add "Rate TapSense" option in settings

- Introduced a new "Rate TapSense" option in the settings that opens the Play Store review page directly.
- Integrated the Play In-App Review API to prompt users for a review after their second successful tap test.
- Added necessary data persistence for tracking tap test success count and review request status.
- Updated localization for the new settings option across multiple languages.

Author: nagarjunavs

CHANGELOG.md

@@ -6,6 +6,16 @@ with the `0.1.0` release.
 
 ## [Unreleased]
 
+### Added
+
+- Sample app: a "Rate TapSense" row in Settings, opening the Play Store listing directly
+  (`market:` URI, falling back to the web listing). Separately, the Play In-App Review API
+  (`com.google.android.play:review:2.0.2`) is now requested at most once per install, after the
+  user's second successful tap test - a real signal they got value from the app's core promise,
+  without asking on the very first (possibly just curious) success. The request/launch itself is
+  fire-and-forget per Google's guidance (the API never reports whether the dialog was shown or
+  reviewed), and Google's own quota is still the final word on whether it actually appears.
+
 ### Fixed
 
 - Sample app: changing the app's language via **Settings → Apps → TapSense → Language** (the

app/build.gradle.kts

@@ -27,7 +27,7 @@ android {
         applicationId = "com.tapsense.app"
         minSdk = 26
         targetSdk = 36
-        versionCode = 6
+        versionCode = 7
         versionName = "1.0.0"
 
         testInstrumentationRunner = "com.tapsense.app.HiltTestRunner"
@@ -145,6 +145,9 @@ dependencies {
 
     implementation(libs.kotlinx.coroutines.android)
     implementation(libs.kotlinx.serialization.json)
+    // FakeReviewManager (used for BuildConfig.DEBUG in InAppReviewLauncher.kt) ships inside this
+    // same artifact as of 2.0.x - no separate review-testing artifact exists for this version.
+    implementation(libs.play.review)
 
     testImplementation(libs.junit)
     testImplementation(libs.mockk)

app/src/main/kotlin/com/tapsense/app/data/settings/TapSenseSettings.kt

@@ -19,6 +19,8 @@ data class TapSenseSettings(
     val hapticsEnabled: Boolean = true,
     val reduceMotion: Boolean = false,
     val appearanceMode: AppearanceMode = AppearanceMode.SYSTEM,
+    val tapTestSuccessCount: Int = 0,
+    val reviewFlowRequested: Boolean = false,
 ) {
     val hasManualPhoneOverride: Boolean
         get() = selectedPhoneManufacturer != null && selectedPhoneModel != null

app/src/main/kotlin/com/tapsense/app/data/settings/TapSenseSettingsRepository.kt

@@ -4,6 +4,7 @@ import androidx.datastore.core.DataStore
 import androidx.datastore.preferences.core.Preferences
 import androidx.datastore.preferences.core.booleanPreferencesKey
 import androidx.datastore.preferences.core.edit
+import androidx.datastore.preferences.core.intPreferencesKey
 import androidx.datastore.preferences.core.stringPreferencesKey
 import com.nfclocator.core.domain.model.FormFactor
 import kotlinx.coroutines.flow.Flow
@@ -33,6 +34,8 @@ class TapSenseSettingsRepository @Inject constructor(
             appearanceMode = prefs[Keys.APPEARANCE_MODE]
                 ?.let { runCatching { AppearanceMode.valueOf(it) }.getOrNull() }
                 ?: AppearanceMode.SYSTEM,
+            tapTestSuccessCount = prefs[Keys.TAP_TEST_SUCCESS_COUNT] ?: 0,
+            reviewFlowRequested = prefs[Keys.REVIEW_FLOW_REQUESTED] ?: false,
         )
     }
 
@@ -69,6 +72,34 @@ class TapSenseSettingsRepository @Inject constructor(
         dataStore.edit { it[Keys.APPEARANCE_MODE] = mode.name }
     }
 
+    /**
+     * Records one more successful tap test and reports whether *this* success is the moment to
+     * request an in-app review: the running count just reached [reviewTriggerCount] for the first
+     * time, and the flow has never been requested before on this install. The count keeps
+     * incrementing past the trigger (so it stays a true lifetime count, not capped at the
+     * threshold), but [Keys.REVIEW_FLOW_REQUESTED] latches to true the moment eligibility is
+     * reported, permanently ruling out every later call - the review flow is only ever requested
+     * once per install, matching Google's own guidance not to over-ask (see
+     * [com.tapsense.app.util.requestInAppReviewSafely]).
+     *
+     * Both the increment and the latch happen inside one [DataStore.edit] transaction so a caller
+     * can't observe a count bump without the accompanying requested-flag update, or vice versa.
+     */
+    suspend fun recordTapTestSuccessAndCheckReviewEligibility(reviewTriggerCount: Int): Boolean {
+        var eligible = false
+        dataStore.edit { prefs ->
+            val updatedCount = (prefs[Keys.TAP_TEST_SUCCESS_COUNT] ?: 0) + 1
+            prefs[Keys.TAP_TEST_SUCCESS_COUNT] = updatedCount
+
+            val alreadyRequested = prefs[Keys.REVIEW_FLOW_REQUESTED] ?: false
+            eligible = !alreadyRequested && updatedCount >= reviewTriggerCount
+            if (eligible) {
+                prefs[Keys.REVIEW_FLOW_REQUESTED] = true
+            }
+        }
+        return eligible
+    }
+
     private object Keys {
         val ONBOARDING_COMPLETED = booleanPreferencesKey("onboarding_completed")
         val PHONE_MANUFACTURER = stringPreferencesKey("selected_phone_manufacturer")
@@ -77,5 +108,7 @@ class TapSenseSettingsRepository @Inject constructor(
         val HAPTICS_ENABLED = booleanPreferencesKey("haptics_enabled")
         val REDUCE_MOTION = booleanPreferencesKey("reduce_motion")
         val APPEARANCE_MODE = stringPreferencesKey("appearance_mode")
+        val TAP_TEST_SUCCESS_COUNT = intPreferencesKey("tap_test_success_count")
+        val REVIEW_FLOW_REQUESTED = booleanPreferencesKey("review_flow_requested")
     }
 }

app/src/main/kotlin/com/tapsense/app/ui/navigation/TapSenseNavHost.kt

@@ -27,6 +27,7 @@ import com.tapsense.app.ui.taptest.TapTestRoute
 import com.tapsense.app.ui.troubleshoot.TroubleshootRoute
 import com.tapsense.app.util.PRIVACY_POLICY_URL
 import com.tapsense.app.util.openNfcSettingsSafely
+import com.tapsense.app.util.openPlayStoreListingSafely
 import com.tapsense.app.util.sendFeedbackEmailSafely
 import com.tapsense.app.util.openUrlSafely
 
@@ -126,6 +127,7 @@ fun TapSenseNavHost(
                             navController.navigate(TapSenseDestinations.TROUBLESHOOT)
                         },
                         onContactSupportClick = { context.sendFeedbackEmailSafely() },
+                        onRateAppClick = { context.openPlayStoreListingSafely() },
                         onPrivacyClick = { context.openUrlSafely(PRIVACY_POLICY_URL) },
                 )
             }

app/src/main/kotlin/com/tapsense/app/ui/settings/SettingsScreen.kt

@@ -38,6 +38,7 @@ fun SettingsRoute(
     onOpenNfcSettings: () -> Unit,
     onHelpCenterClick: () -> Unit,
     onContactSupportClick: () -> Unit,
+    onRateAppClick: () -> Unit,
     onPrivacyClick: () -> Unit,
     modifier: Modifier = Modifier,
     viewModel: SettingsViewModel = hiltViewModel(),
@@ -53,6 +54,7 @@ fun SettingsRoute(
         onOpenNfcSettings = onOpenNfcSettings,
         onHelpCenterClick = onHelpCenterClick,
         onContactSupportClick = onContactSupportClick,
+        onRateAppClick = onRateAppClick,
         onPrivacyClick = onPrivacyClick,
         onHapticsChange = viewModel::setHapticsEnabled,
         onReduceMotionChange = viewModel::setReduceMotion,
@@ -70,6 +72,7 @@ private fun SettingsScreen(
     onOpenNfcSettings: () -> Unit,
     onHelpCenterClick: () -> Unit,
     onContactSupportClick: () -> Unit,
+    onRateAppClick: () -> Unit,
     onPrivacyClick: () -> Unit,
     onHapticsChange: (Boolean) -> Unit,
     onReduceMotionChange: (Boolean) -> Unit,
@@ -148,6 +151,10 @@ private fun SettingsScreen(
             Text("›", style = MaterialTheme.typography.bodyMedium, color = MaterialTheme.colorScheme.onSurfaceVariant)
         }
         HorizontalDivider()
+        SettingsRow(label = stringResource(R.string.settings_rate_app), onClick = onRateAppClick) {
+            Text("›", style = MaterialTheme.typography.bodyMedium, color = MaterialTheme.colorScheme.onSurfaceVariant)
+        }
+        HorizontalDivider()
         SettingsRow(label = stringResource(R.string.settings_privacy), onClick = onPrivacyClick) {
             Text("›", style = MaterialTheme.typography.bodyMedium, color = MaterialTheme.colorScheme.onSurfaceVariant)
         }

app/src/main/kotlin/com/tapsense/app/ui/taptest/TapTestScreen.kt

@@ -50,6 +50,7 @@ import com.tapsense.app.ui.theme.tapSenseFilled
 import com.tapsense.app.ui.theme.tapSenseOutlined
 import com.tapsense.app.ui.theme.tapSenseOutlinedBorder
 import com.tapsense.app.util.openNfcSettingsSafely
+import com.tapsense.app.util.requestInAppReviewSafely
 
 /**
  * The real "does this tap zone actually work" flow: registers as a live NFC reader
@@ -71,6 +72,7 @@ fun TapTestRoute(
     val activity = context as? Activity
     val hapticFeedback = LocalHapticFeedback.current
     val hapticsEnabled by viewModel.hapticsEnabled.collectAsState()
+    val reviewFlowEligible by viewModel.reviewFlowEligible.collectAsState()
 
     DisposableEffect(activity) {
         if (activity != null) {
@@ -89,6 +91,15 @@ fun TapTestRoute(
         }
     }
 
+    // Fires at most once per install (see TapTestViewModel.onTagDetected) - the dismissible
+    // system review sheet itself, not this screen, is what the user actually sees or ignores.
+    LaunchedEffect(reviewFlowEligible) {
+        if (reviewFlowEligible) {
+            activity?.requestInAppReviewSafely()
+            viewModel.onReviewFlowRequested()
+        }
+    }
+
     TapTestScreen(
         uiState = uiState,
         antennaState = antennaState,

app/src/main/kotlin/com/tapsense/app/ui/taptest/TapTestViewModel.kt

@@ -28,6 +28,13 @@ import javax.inject.Inject
 private const val DEFAULT_TIMEOUT_MILLIS = 25_000L
 private const val TAG = "TapTestViewModel"
 
+/**
+ * Ask for a review after the *second* successful tap test, not the first - the first success may
+ * just be onboarding curiosity, while a second success is a real signal the user got value from
+ * the app's core promise (a tap zone that actually works).
+ */
+private const val REVIEW_TRIGGER_TAP_TEST_SUCCESS_COUNT = 2
+
 /**
  * Drives the Tap Test screen's state machine. [startListening]/[stopListening] are the only
  * methods that touch the real `NfcAdapter.enableReaderMode` boundary (via
@@ -67,6 +74,15 @@ class TapTestViewModel @Inject constructor(
     /** The resolved device's marker, shown behind the Ready/Detecting content - matches Home/My Phone/Tap Guide. */
     val antennaState: StateFlow<AntennaLocatorUiState?> = _antennaState.asStateFlow()
 
+    private val _reviewFlowEligible = MutableStateFlow(false)
+    /**
+     * One-shot signal that this is the moment to fire the Play In-App Review flow (see
+     * [onTagDetected]). The screen observes this, launches the OS flow with its `Activity`, and
+     * calls [onReviewFlowRequested] to consume it - the boolean going back to `false` is what
+     * stops the same signal from re-firing on the next recomposition (e.g. after a rotation).
+     */
+    val reviewFlowEligible: StateFlow<Boolean> = _reviewFlowEligible.asStateFlow()
+
     val hapticsEnabled: StateFlow<Boolean> = settingsRepository.settings
         .map { it.hapticsEnabled }
         .stateIn(viewModelScope, SharingStarted.Eagerly, true)
@@ -121,6 +137,19 @@ class TapTestViewModel @Inject constructor(
     fun onTagDetected() {
         timeoutJob?.cancel()
         _uiState.value = TapTestUiState.Detected
+        viewModelScope.launch {
+            val eligible = settingsRepository.recordTapTestSuccessAndCheckReviewEligibility(
+                REVIEW_TRIGGER_TAP_TEST_SUCCESS_COUNT,
+            )
+            if (eligible) {
+                _reviewFlowEligible.value = true
+            }
+        }
+    }
+
+    /** Call once the screen has launched (or attempted to launch) the in-app review flow. */
+    fun onReviewFlowRequested() {
+        _reviewFlowEligible.value = false
     }
 
     /**

app/src/main/kotlin/com/tapsense/app/util/InAppReviewLauncher.kt

@@ -0,0 +1,50 @@
+package com.tapsense.app.util
+
+import android.app.Activity
+import android.util.Log
+import com.google.android.play.core.review.ReviewManager
+import com.google.android.play.core.review.ReviewManagerFactory
+import com.google.android.play.core.review.testing.FakeReviewManager
+import com.tapsense.app.BuildConfig
+
+private const val TAG = "InAppReview"
+
+/**
+ * Fires the Play In-App Review flow from [this] activity. Fire-and-forget by design, per Google's
+ * own guidance: the API never reveals whether the dialog was actually shown or whether the user
+ * reviewed (it applies its own undisclosed quota - most calls are silent no-ops), and a failed
+ * request must never change the app's normal flow. So there is nothing meaningful to return to
+ * the caller either way; this only decides *when to ask*, not whether the OS agrees to show it.
+ * Both outcomes are still logged (never surfaced to the user) so a real failure is diagnosable
+ * instead of a silent black box - see the "Common gotchas" table at
+ * https://developer.android.com/guide/playcore/in-app-review/test.
+ *
+ * Call sites are responsible for their own "don't ask too often" gating (see
+ * [com.tapsense.app.data.settings.TapSenseSettingsRepository.recordTapTestSuccessAndCheckReviewEligibility])
+ * - unlike [openPlayStoreListingSafely], which a user can trigger from Settings as often as they like.
+ *
+ * The real [ReviewManagerFactory]-created manager only ever succeeds for a build installed
+ * *through* Google Play (an internal test track, closed/open testing, or production, with that
+ * Google account as the Play Store's primary account and no existing review) - never a debug
+ * build run from Android Studio, `adb install`, or even a sideloaded release APK; on any of those
+ * `requestReviewFlow()` fails every time, regardless of how many times this is called or how the
+ * app decided to call it. [FakeReviewManager] can't render the real dialog either (it only fakes
+ * a successful `Task` result, per Google's docs), but swapping to it for [BuildConfig.DEBUG]
+ * lets the logs below confirm the trigger/eligibility logic itself reached `launchReviewFlow`
+ * correctly, isolating "nothing shows" during local testing to that Play-install requirement
+ * rather than a bug in this app's own gating.
+ */
+fun Activity.requestInAppReviewSafely() {
+    val manager: ReviewManager = if (BuildConfig.DEBUG) FakeReviewManager(this) else ReviewManagerFactory.create(this)
+    val request = manager.requestReviewFlow()
+    request.addOnCompleteListener { task ->
+        if (task.isSuccessful) {
+            Log.i(TAG, "requestReviewFlow succeeded, launching review flow")
+            manager.launchReviewFlow(this, task.result)
+        } else {
+            // Expected on any build not installed through Play (see the doc link above) - never
+            // surfaced to the user or allowed to change the app's flow, only logged.
+            Log.w(TAG, "requestReviewFlow failed - not installed through Play, or quota declined", task.exception)
+        }
+    }
+}

app/src/main/kotlin/com/tapsense/app/util/UrlLauncher.kt

@@ -12,6 +12,14 @@ const val PRIVACY_POLICY_URL = "https://nagarjunavs.github.io/tapsense/android/p
 /** Support inbox for tester/user feedback - the only feedback channel the app offers. */
 const val SUPPORT_EMAIL = "nagarjunavs.dev@gmail.com"
 
+/**
+ * The published Play Store package id - deliberately not [BuildConfig.APPLICATION_ID]. Debug
+ * builds suffix that with ".debug" (see `applicationIdSuffix` in build.gradle.kts), which has no
+ * Play Store listing at all, so a debug build would otherwise send the "Rate" button to a listing
+ * that doesn't exist.
+ */
+private const val PLAY_STORE_PACKAGE_ID = "com.tapsense.app"
+
 /**
  * Opens [url] in the user's browser, or does nothing if there's no app installed that can handle it
  * (mirrors [openNfcSettingsSafely]'s no-op-on-`ActivityNotFoundException` behavior).
@@ -49,3 +57,18 @@ fun Context.sendFeedbackEmailSafely() {
         // No email app available to handle this - silently no-op rather than crash.
     }
 }
+
+/**
+ * Opens this app's Play Store listing - used by the Settings screen's "Rate" row, a direct,
+ * always-available path to leave a review (unlike [requestInAppReviewSafely], which Google's own
+ * quota may silently decline to show). Prefers a `market:` URI, which the Play Store app resolves
+ * directly to the review tab without a browser hop; falls back to the web listing via
+ * [openUrlSafely] if the Play Store app isn't installed (e.g. some emulator images).
+ */
+fun Context.openPlayStoreListingSafely() {
+    try {
+        startActivity(Intent(Intent.ACTION_VIEW, Uri.parse("market://details?id=$PLAY_STORE_PACKAGE_ID")))
+    } catch (e: ActivityNotFoundException) {
+        openUrlSafely("https://play.google.com/store/apps/details?id=$PLAY_STORE_PACKAGE_ID")
+    }
+}