Skip to main content

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.
Check where your session is stored:
Common causes:
  1. Cookies not set correctly
  2. Cookies don’t support localhost (Despia local server)
  3. localStorage cleared by system
  4. Session validated server-side but app is offline
  5. 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:
React implementation:
Server-side redirect (Next.js):

Problem: Cookies aren’t persisting between sessions.

Set cookies correctly (core concept)

Wrong:
Right:
Helper function:
If empty:
  • 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 from http://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:
Check if running on localhost:
Important: Don’t set 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. Core concept - works everywhere:
React implementation:

Option B: Storage Vault (native only)

Requires Despia Runtime V3.5+

Storage Vault requires Despia native runtime version 3.5 or higher. For apps on older versions, use localStorage instead.
Works for: Native Despia apps (V3.5+), persistent across uninstall/reinstall
React implementation:
Storage Vault benefits:
  • Persists across uninstall/reinstall
  • Syncs across devices (iCloud/Google)
  • Can require Face ID/Touch ID
  • Most reliable for long-term sessions
When to use localStorage vs Vault:
  • 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:
React implementation:
Why hybrid?
  • 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:
React implementation:

Complete app load check

Here’s a complete auth check that handles all cases: React implementation:
Core logic:

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
Localhost (Despia local server):
  • Cookies work on http://localhost
  • No Secure flag on localhost cookies
  • Auth persists after app restart
Offline:
  • User logs in online, goes offline, reopens → Still logged in
  • User can navigate app while offline
  • Session doesn’t require server validation
Edge cases:
  • User visits /auth when logged in → Redirects to /dashboard
  • User visits /dashboard when 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

Fix: Also save to localStorage

Mistake 2: Not redirecting from /auth

Fix: Check for session and redirect

Mistake 3: Cookies without expiry

Fix: Set expiration date

Mistake 4: Secure flag on localhost

Fix: Only set Secure on HTTPS

Mistake 5: Not handling token refresh

Fix: Refresh token before expiry

Mistake 6: Using vault without checking Despia runtime

Fix: Check user agent includes ‘despia’ before using vault

Debugging in native apps

Important: Native apps can’t see console.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:
How to use:
  1. Paste this code into your login/auth page where the error occurs
  2. Open app, you’ll see a red box with debug info
  3. Tap the text area - it selects all text
  4. Copy the text to check values
  5. Delete the entire debug div when done

React version (quick)

Super minimal version

Just want to see token status? Add this one line:
Remember: Remove all debug code before production!

Remember

The golden rule: Store auth in multiple places.
  1. Cookies - Best for server validation when online
  2. localStorage - Works offline, survives app restart, universally supported
  3. Storage Vault - Most reliable, survives uninstall (Despia native V3.5+ only)
Always redirect:
  • Logged in users on /auth/dashboard
  • Logged out users on /dashboard/auth
Handle offline:
  • Don’t require server calls to check auth
  • Use localStorage (or Vault for Despia V3.5+) for offline-compatible auth
Check runtime version:
  • 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