When Should a Capacitor App Keep androidScheme at http Instead of https?

Question

Capacitor apps can behave differently between a local dev run and a release build because several capacitor.config options change the WebView's loading target and origin. A server.url pointing at a LAN dev server is reachable on the developer's network but not from an installed production build, and server.cleartext permits plain HTTP locally while a production network policy may require HTTPS.
A less visible difference is the Android scheme default. Capacitor 3 changed it from http to https, so the WebView origin becomes something like https://localhost rather than http://localhost. Data keyed to the old origin — localStorage, cookies, and origin-based CORS assumptions — may not follow the app across that change. Option names and defaults vary by major version, so the installed version's documentation and migration guide are the reference point.
The unresolved decision: keep androidScheme at https for a secure origin, or retain http for continuity with existing stored data. The trade-off depends on whether an app actually holds origin-bound state.
Which signals should decide that choice for an app with existing users? Does origin-bound localStorage or cookies change the answer? What should be confirmed about the effective origin before committing?

Tasadduq Burney · Answer

Answer the question first
Keep androidScheme set to http only if your app relies on origin‑bound client‑side data (localStorage, IndexedDB, or cookies) that is still scoped to the http://localhost origin and has not been migrated to the https://localhost origin. If no such data exists, or you have already migrated it, switch androidScheme to https to align with Capacitor 3+ defaults and enforce a secure origin.
Likely explanation vs. confirmed facts
Likely explanation (based on typical behavior)

Capacitor 2 defaulted the Android WebView scheme to http; Capacitor 3 changed the default to https.
When the scheme changes, the WebView origin changes from http://localhost to https://localhost, breaking any client‑storage that is tied to the old origin.
Keeping http preserves access to existing localStorage/cookies but disables mixed‑content protections and may trigger Android cleartext‑traffic restrictions.

Confirmed facts (from Capacitor documentation)

The androidScheme option directly controls the scheme used for the WebView loading URL.
Capacitor 3+ release notes list the default change from http to https.
Android 9+ (API 28) blocks cleartext traffic unless usesCleartextTraffic=true is set in the manifest.

Steps needed for this case

Check your Capacitor version (npx cap -v) to confirm whether the default is http (v2) or https (v3+).
Run a development build and log window.location.origin to see the effective scheme.
Inspect localStorage and document.cookie; note if any keys are scoped to http://localhost.
If you find origin‑bound data on the http origin that has not been migrated, keep androidScheme = http and plan a data‑migration strategy before switching.
If no such data exists (or you have already migrated it), set androidScheme = https and, for Android 9+, ensure usesCleartextTraffic is false or omitted.

One missing diagnostic detail
Before finalizing the decision, please confirm: Does your app currently store any data in localStorage, IndexedDB, or cookies that is scoped to the http://localhost origin? The answer determines whether keeping http is necessary to avoid apparent data loss for existing users.

When Should a Capacitor App Keep androidScheme at http Instead of https?

1 answer

Answer the question first

Likely explanation vs. confirmed facts

Likely explanation (based on typical behavior)

Confirmed facts (from Capacitor documentation)

Steps needed for this case

One missing diagnostic detail

Your perspective belongs here.

0 question comments