Quick diagnosis
Important for native apps:
console.log() won’t be visible. For debugging, create a /debug page (see “Debugging in native apps” section) or display values on screen.- Cookies not set correctly
- Cookies don’t support
localhost(Despia local server) - localStorage cleared by system
- Session validated server-side but app is offline
- Users landing on /auth page without redirect
Solution 1: Redirect logged-in users
Problem: User opens app, lands on/auth or /login, even though they have a valid session.
Fix: Check for session on protected routes and redirect.
Core concept:
Solution 2: Fix cookie configuration
Problem: Cookies aren’t persisting between sessions.Set cookies correctly (core concept)
Wrong:Check cookie attributes
- Cookie expired
- Wrong domain/path
- Secure flag on HTTP site
- SameSite blocking it
Solution 3: Support localhost cookies
Problem: Using Despia’s local server (app served fromhttp://localhost), but cookies set for yourapp.com don’t work.
The issue: Cookies from yourapp.com don’t apply to localhost.
Fix: Set cookies for both domains:
Secure flag for localhost:
Solution 4: Use offline-compatible storage
Problem: Cookies require server validation. When app is offline, cookies can’t be validated, user appears logged out. Fix: Store auth state in offline-compatible storage.Option A: localStorage (recommended)
Core concept - works everywhere:Option B: Storage Vault (native only)
Works for: Native Despia apps (V3.5+), persistent across uninstall/reinstall- Persists across uninstall/reinstall
- Syncs across devices (iCloud/Google)
- Can require Face ID/Touch ID
- Most reliable for long-term sessions
- localStorage: Works everywhere, simple, reliable
- Vault: Best for native apps on Despia V3.5+, survives uninstall
Solution 5: Hybrid approach
Best practice: Use cookies, localStorage, and optionally vault for maximum reliability. Core concept:- Cookies work best with server validation (when online)
- localStorage works offline and is universally supported
- Vault storage survives uninstall (native Despia V3.5+ only)
- Redundancy means users rarely get logged out
Solution 6: Session refresh strategy
Problem: Token expired, user appears logged out. Fix: Refresh token before expiry. Core concept:Complete app load check
Here’s a complete auth check that handles all cases: React implementation:Testing checklist
Test these scenarios to ensure users stay logged in: Basic persistence:- User logs in, closes app, reopens → Still logged in
- User logs in, force quit app, reopens → Still logged in
- User logs in, waits 24 hours, reopens → Still logged in
- Cookies work on
http://localhost - No
Secureflag on localhost cookies - Auth persists after app restart
- User logs in online, goes offline, reopens → Still logged in
- User can navigate app while offline
- Session doesn’t require server validation
- User visits
/authwhen logged in → Redirects to/dashboard - User visits
/dashboardwhen logged out → Redirects to/auth - Token expires → User redirected to login
- Refresh token used when token expires soon
Storage comparison
Recommendation:
- Web app: Cookies + localStorage
- Despia native (V3.5+): Storage Vault + localStorage + cookies (hybrid)
- Despia native (< V3.5): localStorage + cookies
- Offline-first: localStorage or Storage Vault (no cookies)
Common mistakes
Mistake 1: Only using cookies
Mistake 2: Not redirecting from /auth
Mistake 3: Cookies without expiry
Mistake 4: Secure flag on localhost
Mistake 5: Not handling token refresh
Mistake 6: Using vault without checking Despia runtime
Debugging in native apps
Important: Native apps can’t seeconsole.log(). The best way to debug is using a text area with values - it’s copyable, selectable, and works everywhere.
Why text areas work best:
- Tap once to select all text
- Long press to copy
- Shows lots of data in one place
- Works in every framework
- No special libraries needed
Copy-paste debug code (easiest)
Just paste this HTML anywhere on your/auth or /login page:
- Paste this code into your login/auth page where the error occurs
- Open app, you’ll see a red box with debug info
- Tap the text area - it selects all text
- Copy the text to check values
- Delete the entire debug div when done
React version (quick)
Super minimal version
Just want to see token status? Add this one line:Remember
The golden rule: Store auth in multiple places.- Cookies - Best for server validation when online
- localStorage - Works offline, survives app restart, universally supported
- Storage Vault - Most reliable, survives uninstall (Despia native V3.5+ only)
- Logged in users on
/auth→/dashboard - Logged out users on
/dashboard→/auth
- Don’t require server calls to check auth
- Use localStorage (or Vault for Despia V3.5+) for offline-compatible auth
- Storage Vault requires Despia runtime V3.5+
- Always check user agent includes ‘despia’ before using vault
- Use localStorage as fallback for older versions
For support or questions, contact: support@despia.com