From f25c1151a62e138674b3d09cc1ffe8b926624c92 Mon Sep 17 00:00:00 2001 From: ehsan shariati Date: Fri, 4 Sep 2026 17:51:24 -0400 Subject: [PATCH] docs: name the battery restriction behind a wallet that wedges every time, and shorten the wait Two updates to the wallet hand-off guidance. The "give the page a few seconds" note now says "a second or two". As of functionland/fxblox-web#36 the app restarts its relay socket the moment the tab comes back from a wallet rather than trusting a socket that only claims to be open, so the approval is fetched at once instead of after Chrome's TCP stack notices. The advice not to tap again or reload in the meantime stands. The stuck-splash-screen tip now says what to do when it happens EVERY time: Android is restricting MetaMask in the background, so it is suspended or killed on every switch away and cannot handle the request it is resumed for. Settings > Apps > MetaMask > Battery > Unrestricted, and the same for the browser. This is the setting the mobile FxBlox app always needed for the same prompts -- the legacy section of this page has said so for a long time -- and the web app is subject to it in exactly the same way. A web page cannot change it for the user, so the page has to tell them. Same line added to the troubleshooting list and to Switch Chain Troubleshooting. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_013BpqXrkEPA9odTyRdK5Mnx --- docs/functionyard/fxblox-app.md | 11 ++++++----- docs/functionyard/troubleshooting/switch-chain.md | 1 + 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/functionyard/fxblox-app.md b/docs/functionyard/fxblox-app.md index 62f627c..0d1d780 100644 --- a/docs/functionyard/fxblox-app.md +++ b/docs/functionyard/fxblox-app.md @@ -58,8 +58,8 @@ Your password plus that one signature is what produces your identity. **Write th On a phone this takes two taps, on purpose: the first **Sign with Wallet** connects the wallet, and the second sends it the signature request. A browser is only allowed to switch to another app from a real tap, so the second one cannot happen for you. -:::info Coming back from your wallet? Give the page a few seconds -After you approve in MetaMask — or any other wallet — and return to the FxBlox tab, the page can still show **Connecting Wallet…** for a few seconds before it catches up. That is normal. Android suspends the browser's connection while you are away in another app, and it has to be re-established before the page can see what you approved. +:::info Coming back from your wallet? Give the page a moment +After you approve in MetaMask — or any other wallet — and return to the FxBlox tab, the page can still show **Connecting Wallet…** for a second or two before it catches up. That is normal. Android suspends the browser's connection while you are away in another app; the app reconnects the moment you return, and then sees what you approved. **Wait for it rather than helping.** Tapping the button again, reloading the tab or going back a screen cancels the request you just approved, and you have to start the whole hand-off over. Only if nothing has changed after roughly half a minute is something actually wrong. ::: @@ -67,9 +67,9 @@ After you approve in MetaMask — or any other wallet — and return to the FxBl :::tip Wallet opened but stuck on its splash screen? This happens on Android, most often on the first signature right after connecting: MetaMask comes to the front and then sits on its splash screen without ever showing the prompt. -**Close MetaMask completely from your recent apps**, return to the FxBlox tab, and tap **Open wallet to approve**. That is the step that clears it — tapping the button again *without* closing MetaMask first will simply open it back onto the same stuck screen. +**Close MetaMask completely from your recent apps**, return to the FxBlox tab, and tap **Open wallet to approve**. That is the step that clears it — tapping the button again *without* closing MetaMask first will simply open it back onto the same stuck screen. Your signature request stays valid throughout, so nothing is lost and you do not need to start setup again. -Your signature request stays valid throughout, so nothing is lost and you do not need to start setup again. This is a fault inside the wallet app; a web page cannot reach into it and restart it for you. +**If it happens every time, fix the cause:** Android is restricting MetaMask in the background, so it is suspended or killed the moment you switch away, and a wallet resumed from that state cannot handle the request it is being opened for. Go to **Settings → Apps → MetaMask → Battery** and choose **Unrestricted**; do the same for your browser (Chrome or Edge). This is the same setting the mobile FxBlox app always needed for the connect and sign prompts to appear, and with it in place the wallet comes forward already showing the prompt. A web page cannot change it for you. ::: ### 4. Connect to your Blox @@ -175,8 +175,9 @@ The Blox reconnects to the network and saves chain history automatically. - **Chrome's Bluetooth chooser is empty.** Leave it open for up to 90 seconds — the Blox advertises periodically rather than continuously. Make sure Bluetooth is switched on, and that the browser itself is allowed to use it (see the macOS and Android notes below). - **On macOS**, Chrome needs two permissions from the system or it will fail quietly. Grant both under **System Settings → Privacy & Security**: **Bluetooth** (otherwise the device chooser stays empty) and **Local Network** (otherwise the app cannot reach the Blox over Wi-Fi). Quit and reopen Chrome after changing them. - **On Android**, the browser needs the location / nearby-devices permission before it can scan for Bluetooth devices. -- **The page still says "Connecting Wallet…" after you approved.** Wait a few seconds. The browser's connection is suspended while you are away in your wallet and has to be re-established on the way back, so the page notices a little after you do. Do not tap again or reload — that cancels the request you just approved. +- **The page still says "Connecting Wallet…" after you approved.** Give it a second or two. The browser's connection is suspended while you are away in your wallet; the app reconnects when you return and then sees the approval. Do not tap again or reload — that cancels the request you just approved. - **The wallet does not come back after signing.** Switch back to the FxBlox tab yourself. If MetaMask is stuck on its splash screen, close it fully from your recent apps and then tap **Open wallet to approve** — tapping without closing it first only returns you to the same stuck screen. The signature request stays valid either way. +- **MetaMask sticks on its splash screen every time.** Android is restricting it in the background. Set **MetaMask** and your **browser** to **Unrestricted** under **Settings → Apps → (app) → Battery**. See the tip under [Set your identity](#3-set-your-identity). - **Connection problems at the final step.** Connect to the same Wi-Fi as the Blox, reload the page, and use **Reconnect to existing blox**. If that does not work, restart the Blox, wait for the flashing light blue, and set it up again. - **Starting completely over.** The browser equivalent of uninstalling and reinstalling the app is **Clear app storage** on the *Set identity* screen. It deletes everything FxBlox stored in this browser — identity, Blox list, settings and caches — and reloads the page. - **Nothing loads after a new release.** Reload the tab. If a "new version available" prompt appears, accept it. diff --git a/docs/functionyard/troubleshooting/switch-chain.md b/docs/functionyard/troubleshooting/switch-chain.md index 2daa2b9..83290a4 100644 --- a/docs/functionyard/troubleshooting/switch-chain.md +++ b/docs/functionyard/troubleshooting/switch-chain.md @@ -85,6 +85,7 @@ On a phone, the browser's connection to your wallet is suspended while you are a ### MetaMask Connection Problems - **Give it a few seconds first** if the app still says "Connecting Wallet…" after you came back from MetaMask — on a phone the page catches up a little after you do, and tapping again in the meantime cancels what you just approved - **On Android, if MetaMask opens and sits on its splash screen**, close it completely from your recent apps before coming back and tapping again — tapping without closing it first only returns you to the same stuck screen +- **If that happens every time**, Android is restricting MetaMask in the background: set MetaMask and your browser to **Unrestricted** under **Settings → Apps → (app) → Battery** - **Refresh the MetaMask extension** if it appears unresponsive - **Check MetaMask permissions** for the FxBlox app - **Try using a different browser** if issues persist