Never Confuse Fresh, Update, and Reinstall

"First launch" is one phrase, but in practice there are three distinct situations. Handle them with a single flag and something always breaks.

• Fresh install (first run): first launch ever on this device
• First launch after an update: the app version rose within the same install
• Reinstall: deleted once and installed again

The foundation for telling these apart is a durable install identifier in SecureStore. Because SecureStore can survive deletion on iOS, we turn that into "reinstall on the same device" detection.

// install-identity.ts — resolve the install situation as three states
import * as SecureStore from "expo-secure-store";
import AsyncStorage from "@react-native-async-storage/async-storage";
import * as Application from "expo-application";
import { randomUUID } from "expo-crypto";
 
type InstallState = "fresh" | "update" | "reinstall";
 
export async function resolveInstallState(): Promise<{
  state: InstallState;
  installId: string;
}> {
  const currentVersion = Application.nativeApplicationVersion ?? "0";
 
  // SecureStore can survive deletion on iOS (a persistent layer tied to the device)
  let installId = await SecureStore.getItemAsync("install_id");
  // AsyncStorage is always wiped on delete (a volatile layer tied to the install)
  const lastVersion = await AsyncStorage.getItem("last_version");
 
  let state: InstallState;
  if (lastVersion === null) {
    // AsyncStorage empty = first launch for this install
    // If an id remains in SecureStore, it's a reinstall on the same device
    state = installId ? "reinstall" : "fresh";
  } else if (lastVersion !== currentVersion) {
    state = "update";
  } else {
    state = "fresh"; // strictly a normal launch; let the caller decide handling
  }
 
  if (!installId) {
    installId = randomUUID();
    await SecureStore.setItemAsync("install_id", installId);
  }
  await AsyncStorage.setItem("last_version", currentVersion);
 
  return { state, installId };
}

The crux is how the asymmetry is used. Whether AsyncStorage (the wiped layer) is empty tells you "is this the first launch for this install"; whether an id exists in SecureStore (the surviving layer) tells you "is this a reinstall on the same device." Fresh means both empty; reinstall means AsyncStorage empty and SecureStore filled.

Save expo-application's nativeApplicationVersion in AsyncStorage and update detection comes from the same function. Now "show only on first launch" and "show on every update" sit on separate axes.

Onboarding Is on the Install Axis; What's New Is on the Version Axis

People conflate them, but onboarding and the post-update "What's New" belong to different axes. Onboarding is tied to the install; What's New is tied to the version. Hold them separately and both behave correctly.

// gates.ts — manage the two axes with separate flags
export async function shouldShowOnboarding(): Promise<boolean> {
  // Install axis: fine to re-show on reinstall, so AsyncStorage is enough
  const done = await AsyncStorage.getItem("onboarding_done");
  return done !== "1";
}
 
export async function shouldShowWhatsNew(currentVersion: string): Promise<boolean> {
  // Version axis: keep "which version was seen"
  const seen = await AsyncStorage.getItem("whatsnew_seen_version");
  return seen !== currentVersion;
}

Putting onboarding in AsyncStorage is deliberate. Reinstalling users are often better served by seeing the flow again (someone who bailed early and deleted is, on reinstall, signaling a second attempt). Hold What's New by "seen version" and it appears once per update and not on normal launches. The message at the top of this article — onboarding not showing on reinstall — was a textbook case of having put the onboarding-completed flag into SecureStore. Place install-axis state in the surviving layer and reinstalls no longer return to "first run."

Make the Server Authoritative for Trials and Entitlements

Trial consumption and purchase entitlements must not be judged with device storage. AsyncStorage is wiped on delete, so the trial becomes re-acquirable; SecureStore splits between iOS and Android. Make the server the single authority here.

// trial.ts — query the server keyed by the device identifier (don't use device storage to decide)
export async function checkTrialEligibility(installId: string): Promise<{
  eligible: boolean;
  reason: "new" | "consumed" | "active";
}> {
  const res = await fetch("https://api.example.com/trial/status", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ installId }),
  });
  if (!res.ok) {
    // On no connectivity, fail to "not granted" (prefer a UX hit over fraud)
    return { eligible: false, reason: "consumed" };
  }
  return res.json();
}

Failing to eligible: false (not granted) on no connectivity is the design decision. Fail the other way and you've opened a hole where a trial can be acquired infinitely in airplane mode. For purchases and subscriptions, make the store entitlement (StoreKit/Play, or an entitlement manager like RevenueCat) the primary source rather than your own server, with the device merely caching the result. The device cache exists only to speed up launch; the final verdict on truth lives server-side.

The Android Auto-Backup Pitfall

iOS Keychain survival is famous, but Android has a symmetric trap. With Android Auto Backup enabled, SharedPreferences contents can be restored through the cloud, so some state "survives" even on reinstall. State you wrote assuming it's wiped on iOS can get restored on Android, and behavior splits.

Explicitly exclude sensitive state you don't want restored via the backup rules in android/app/src/main/res/xml/.

<!-- backup_rules.xml — exclude trials and identifiers from cloud restore -->
<full-backup-content>
  <exclude domain="sharedpref" path="trial_state.xml" />
  <exclude domain="sharedpref" path="install_identity.xml" />
</full-backup-content>

Always verify on real devices which storage survives "on which OS, under which operation." This area behaves differently on simulators/emulators than on real hardware, so whenever I add a new piece of state, I run a "delete → reinstall" on a real device once and confirm with my own eyes that first-launch detection and the trial behave as intended.

Migration and Verification Checklist

Finally, the steps for introducing this design into an existing app.

1. Inventory which storage your current first-launch flag lives in (AsyncStorage or SecureStore).
2. Reassign each state to "should be wiped / should survive on reinstall" (use the table above).
3. Separate onboarding-completed into AsyncStorage (install axis) and What's New onto the version axis.
4. Move trial and entitlement decisions from device to server, demoting the device to a cache.
5. Use Android backup rules to exclude sensitive state you don't want restored.
6. Run all three paths on a real device — fresh / update / delete-then-reinstall — and verify each flag's behavior.
7. Confirm in airplane mode that the trial check fails to the "not granted" side on no connectivity.

What pays off in this inventory is the view that storage choice is the spec itself. The moment you decide where to put something, its reinstall behavior is already decided.

Closing

Reinstall bugs look like individual defects, but the root is "not grasping the asymmetry between the wiped layer and the surviving layer." Decide desired behavior per state, place it in the matching layer, and make the server authoritative for money and fraud. Split the install axis from the version axis. That tidy-up alone clears a whole class of symptoms: not returning to first run on reinstall, re-acquirable trials, update notices that never appear.

Start by checking whether your app's first-launch flag lives in AsyncStorage or SecureStore. The placement of a single flag quietly governs the reinstall experience. As an indie developer, I hope it helps anyone growing an app that's meant to be used for a long time.