storehop

v0.7.1: sideloaded APK → Play Store migration runbook

TL;DR for Mike

You’ve been running sideloaded StoreHop APKs since v0.3.x. To finish the beta cycle you need to switch over to the Play Closed Testing install. The signing certificates are different (Play’s own vs. the upload key your APKs are signed with), so Android won’t update one on top of the other — you have to uninstall the sideloaded build first, which would normally lose anything local-only.

v0.7.1 closes the two local-only gaps (your preferences + any unflushed writes) by cloud-syncing them through Firestore, so the post-uninstall Play install rehydrates everything when you sign back in. Five-step process below.

Prerequisites

• You already have v0.7.0 (or an earlier sideloaded build) installed on your phone.
• You’re signed into StoreHop with your Google account.
• I’ve deployed the new Firestore security rules (/userPrefs/{uid}) before you start.
• I’ve sent you the v0.7.1 sideloaded APK (upload-key signed, so it updates in place over your current build — no uninstall yet).

Five steps

1. Install the v0.7.1 sideloaded APK over your current build

Open the APK from wherever I sent it. Android will say “Update existing app?” — yes. Your data stays put; this is an in-place update.

2. Open StoreHop

That’s enough to fire the cloud-prefs reconcile. Your theme, language, sort modes, and the hide-checked-off toggle all upload to Firestore silently in the background. Even if you never open Settings, your prefs are now captured.

3. Tap “Force sync now”

Settings → Data → “Sync before uninstalling” → tap the Force sync now button.

You’ll see one of three states:

• “Syncing N items…“ — the app is pushing pending writes. Wait.
• “Safe to uninstall. Your data is backed up.” — green text. Done.
• “N item(s) couldn’t sync.” — red text + retry button. Tap retry; if it still fails, your network is having a moment. Wait a minute and try once more.

Do NOT uninstall until you see “Safe to uninstall.”

4. Uninstall the sideloaded StoreHop

Settings (Android system Settings, not StoreHop’s) → Apps → StoreHop → Uninstall.

5. Install from Play Closed Testing + sign in

Open the Play Closed Testing link I sent you, install. Open StoreHop. On first launch you’ll see a fresh state (empty list, default theme). Tap Settings → Account → “Sign in with Google” → pick the same Google account you were using before.

The pull runs. Within a few seconds:

• Every item, store, category, xref, store-category-order row, and purchase record loads back in (from Firestore).
• Item photos load on demand (from Firebase Storage).
• Your household membership loads (so if you were in a shared household it still works).
• Your theme, language, sort modes, and hide-checked-off toggle all switch back to what you had (from the new /userPrefs/{uid} doc).

That’s it. Identical UI state to step 2. No data lost.

What “loses NOTHING” actually covers

Survives uninstall?	What it is
✅ Items, stores, categories, xrefs, store-category-order, purchase records	Cloud-synced since v0.4
✅ Item photos	Firebase Storage
✅ Household membership	Cloud-synced since v0.7.0
✅ Theme, language, sort modes, hide-checked-off	New in v0.7.1 — cloud-synced via /userPrefs/{uid}
✅ Any pendingSync = 1 rows	Force-sync-now button drains them before uninstall
⚠️ Cached item photo files	Auto-rehydrates from Storage on next display

What if something goes wrong?

“Force sync now” times out with stuck rows

Tap retry. If it keeps failing:

1. Make sure you’re online (open a browser, load any page).
2. Try again.
3. If still stuck, screenshot the count + tell me. Whatever’s stuck has a content-level issue we can fix or work around. Don’t uninstall yet — those rows will be lost.

After Play install + Google sign-in, my data isn’t back

Wait 30 seconds. The pull is one round-trip per entity (items, stores, categories, etc.); if the network is slow this takes a moment.

If it’s still not back after a minute:

1. Pull-to-refresh on the Items tab.
2. Check Settings → Account → if the cloud-sync banner says “Sync failed,” tap Retry.
3. If still nothing, tell me. Worst case I can manually verify your data is in Firestore and walk you through a recovery.

I uninstalled before “Safe to uninstall”

This is the bad path — anything in the pendingSync = 1 queue when you uninstalled is lost. Items / stores / categories that already made it to Firestore are fine. In practice the sync engine pushes continuously, so the loss surface is usually just whatever edits you made in the last few seconds before uninstall.

Italian or Portuguese language: my picker doesn’t have my language

That’s the OS per-app locale layer, not the app. After the v0.7.1 prefs pull, the localeTag in the new install is set correctly; Android just needs to honour it. Force-quit the app (recents → swipe up) and reopen. If it still doesn’t switch, go to Android system Settings → StoreHop → Languages → pick your language manually.

Why we need this

Three reasons:

1. Play App Signing rewrites the signing cert. When you upload an AAB to Play, Google signs the distributed APK with their own key (the “app signing key”). The APK I built locally for you is signed with the upload key. Different certificates → Android refuses in-place update → uninstall mandatory.

2. Some state is local-only without v0.7.1. Preferences (theme, language, sort modes, hide-checked-off) lived only in Android’s DataStore + the per-app locale API. Both are cert-bound, both wiped on cert-change uninstall.

3. Some writes are queued but unsent. Anything edited offline or during a sync failure has pendingSync = 1 and hasn’t reached Firestore yet. Without a force-flush there’s no way to be sure you’ve drained the queue.

v0.7.1 fixes 2 and 3. 1 is just an Android signing-cert fact of life.