Skip to content

Commit c9e825a

Browse files
committed
docs(docs): say Android needs cleartext for localhost and the console can print a token
A Pixel Fold emulator run showed a bundled build fails with ERR_CLEARTEXT_NOT_PERMITTED even over adb reverse, so the guide now says server.cleartext is required. A failed connection also makes the WebView console print the whole connection URL with the pairing token, which the overlay and security pages now warn about.
1 parent 844ca9e commit c9e825a

3 files changed

Lines changed: 4 additions & 4 deletions

File tree

‎apps/docs/src/content/getting-started/overlay.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -209,7 +209,7 @@ await initOverlay({
209209

210210
Build with `ng build --configuration development,device`. Without the `device` configuration, as in a clone that has no local file, the stub leaves `authToken` out and the page asks for the code.
211211

212-
The token is a development secret. Keep the local file out of git. The page keeps the token in its `localStorage`, and sends it in the query string of its connection URL. See [Pairing tokens](../security.md#pairing-tokens).
212+
The token is a development secret. Keep the local file out of git. The page keeps the token in its `localStorage`, and sends it in the query string of its connection URL. When the connection fails, the browser console prints that whole URL, token included, so don't share console output or device logs from a failed connection. Rotate the token if you did. See [Pairing tokens](../security.md#pairing-tokens).
213213

214214
When the server refuses the token, the overlay logs a warning in the console and asks for the code instead. With `connectionMeta`, it also logs a warning once when it can't reach the server.
215215

‎apps/docs/src/content/guides/capacitor.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,7 @@ The standalone CLI and the Express hub accept `capacitor://localhost` and `https
141141

142142
### Let the app reach your machine
143143

144-
The page is `https://localhost` on Android and the server is plain HTTP, so the Android WebView blocks the connection as mixed content. Android also blocks cleartext traffic. Allow both in a development build:
144+
The page is `https://localhost` on Android and the server is plain HTTP, so the Android WebView can block the connection as mixed content. Android also blocks cleartext traffic, even to `localhost` through `adb reverse`, so without `server.cleartext` the connection fails with `net::ERR_CLEARTEXT_NOT_PERMITTED`. Allow both in a development build:
145145

146146
```ts {4,8-9}
147147
// capacitor.config.ts
@@ -160,7 +160,7 @@ export default config;
160160

161161
If your config already has a `server` or `android` block, add the keys to it instead.
162162

163-
With `adb reverse`, the server is at `http://localhost`, which Chromium may not count as mixed content. Keep both settings anyway: they cost nothing in a development build. Capacitor applies both on `npx cap sync`, which `npx cap run` also runs, so set the flag there: `CAPACITOR_DEVTOOLS=1 npx cap run android`. `server.cleartext` sets `android:usesCleartextTraffic` in the manifest of the `capacitor-cordova-android-plugins` module, which Android merges into the app. Setting `server.androidScheme` to `'http'` also avoids mixed content, but it changes the app's origin, so the WebView no longer sees the data the app stored under `https://localhost`.
163+
With `adb reverse`, the server is at `http://localhost`, which Chromium may not count as mixed content, but cleartext is still blocked, so `server.cleartext` is required. Keep `allowMixedContent` too, for a server on a network address. Capacitor applies both on `npx cap sync`, which `npx cap run` also runs, so set the flag there: `CAPACITOR_DEVTOOLS=1 npx cap run android`. `server.cleartext` sets `android:usesCleartextTraffic` in the manifest of the `capacitor-cordova-android-plugins` module, which Android merges into the app. Setting `server.androidScheme` to `'http'` also avoids mixed content, but it changes the app's origin, so the WebView no longer sees the data the app stored under `https://localhost`.
164164

165165
On iOS, App Transport Security can block plain HTTP to a network address. If it does, allow local networking in a development build's `ios/App/App/Info.plist`:
166166

‎apps/docs/src/content/security.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@ The page sends the token as the `authToken` option of [`initOverlay`](./getting-
125125
- Use a long random value, such as the output of `openssl rand -hex 16`. Tokens shorter than 16 characters are ignored with a warning.
126126
- The servers never print a token. The CLI prints a short hash of each, to tell them apart.
127127
- Tokens stay on the server. They are not part of the config that pages receive in `__connection.json`.
128-
- The page sends the token in the query string of its WebSocket or server-sent events URL (`devframe_auth_token`), so it can show up in proxy or server logs, and in the browser console when the connection is refused, such as a mixed content warning.
128+
- The page sends the token in the query string of its WebSocket or server-sent events URL (`devframe_auth_token`), so it can show up in proxy or server logs, and in the browser console or the device log whenever the connection fails, such as a mixed content or cleartext error. The browser prints that URL itself, so Pangular Inspector can't mask it there.
129129
- The page keeps the token in its `localStorage`, in a WebView too, so it can reconnect. Clear the app's storage to forget it.
130130
- With `--no-auth`, the CLI ignores the tokens, since every client is trusted already.
131131
- To rotate a token, change it, restart the server and rebuild the app with the new value. The servers read the tokens when they start, and a token trusts only the connection that sent it: nothing is saved on the server, so the restart ends every session it trusted. A page that still sends the old token is refused and asks for the one-time code. The `authToken` passed to `initOverlay` wins over the copy in `localStorage`, so an app built with the old token asks for the code on every launch until you rebuild it.

0 commit comments

Comments
 (0)