App Versioning & Auto-Refresh

Documentation for the silent update system

Core Principle

"Every time a user opens Snuggli, it should feel like a fresh, updated, native app – but never at the cost of losing their data or making them wait on a blank screen."

How APP_VERSION Works

  • APP_VERSION is a timestamp-based string: YYYY.MM.DD-HH.MM.SS
  • Set at build time in AppVersionManager.jsx
  • Stored in localStorage as snuggli_app_version
  • Compared against /version.json on each session start
  • If remote version is newer, triggers silent refresh flow

Session Start Triggers

  • First load of the app in a new tab/window
  • Return from background after 30+ minutes (configurable)
  • Login event after logout
  • Manual "Check for updates" from Settings
  • PWA reopening after being fully closed

Silent Update Flow

  • 1. Session start detected → fetch /version.json (no-cache)
  • 2. Compare local vs remote appVersion
  • 3. If different: ensure offline data is safe in localStorage
  • 4. Message service worker to clear old caches
  • 5. Update localStorage with new version
  • 6. Call window.location.reload()
  • 7. New version loads instantly from fresh cache

Data Safety Guarantees

  • Offline queue (snuggli_offline_queue) survives refresh
  • Offline cache (snuggli_offline_cache) survives refresh
  • User preferences and session data preserved
  • SessionInitializer rehydrates and syncs on load
  • No data loss during version updates

Testing New Deployments

  • 1. Update APP_VERSION in AppVersionManager.jsx
  • 2. Deploy version.json with matching appVersion
  • 3. Open app in incognito to test fresh session
  • 4. Or wait 30+ minutes and return to test background refresh
  • 5. Check version logs in localStorage: snuggli_version_logs

Adjusting Session Timeout

  • Edit SESSION_TIMEOUT_MS in AppVersionManager.jsx
  • Default: 30 minutes (30 * 60 * 1000)
  • Shorter = more frequent version checks
  • Longer = better battery life, less network usage
  • Recommended: 30-60 minutes for most use cases

Analytics Events

app_version_check

Logged when version comparison occurs

app_auto_refresh_triggered

Logged when update starts

app_auto_refresh_completed

Logged after successful reload

app_auto_refresh_failed

Logged if update fails

app_version_check_failed

Logged if version.json fetch fails

LocalStorage Keys

snuggli_app_version– Current app version
snuggli_last_active– Last activity timestamp
snuggli_session_id– Current session ID
snuggli_version_logs– Last 50 version events

Last updated: December 2024