Web apps and native apps
How a website, a phone app and a desktop app each reach a person's BSV wallet, and what changes for the connect prompt, the no-wallet case and who the wallet can say is asking.
The Wallet Application Interface is the same everywhere, but the road an app takes to the wallet is not. A website, a phone app and a desktop app each reach the wallet differently, and that changes three things the person sees: what happens when they press Connect, what happens when there is no wallet, and whether the wallet can say for certain who is asking.
Connecting a wallet covers what to ask for once connected. This page covers the route, platform by platform.
The four routes at a glance
| Website, on a computer | Website, on a phone | Desktop app | Phone app | |
|---|---|---|---|---|
| How it reaches the wallet | A wallet running on the same computer, over a local connection | Only from inside a wallet's built-in browser | A wallet running on the same computer, over a local connection | No standard route yet (see below) |
| Who is asking | The site's domain, checked by the browser | The site's domain, checked by the wallet's browser | A name the app gives itself | A name the app gives itself |
| No wallet found | Help them install one; the site keeps working | Opened in an ordinary browser, it cannot connect at all | Help them install one | Help them install one, or pair a phone wallet |
| Where the approval appears | The wallet's window, over the browser | A sheet inside the same app | The wallet's window, over the app | Depends on the route |
| Payments while you are away | Only while the tab is open | Only while the page is open | Can keep running | Limited by the phone's background rules |
Who is asking
This is the difference that matters most for design.
When a website calls the wallet, the request carries the site's domain, and a browser fills that in itself. A page on tickets.example.com cannot claim to be bank.example.com. The wallet can show the domain as a fact.
A desktop or phone app is not inside a browser, so nothing fills the domain in for it. The app states its own name, and the wallet has to take its word. "Example Tickets wants to connect" from an installed app is a claim, not a check.
So the same prompt means two different things, and the wallet should say which.
Do
If you build a wallet, show a domain checked by the browser and a name an app gave itself differently, and say plainly when the name has not been checked.
Don't
Let an installed app that claims a website's name inherit the permissions or allowances already granted to that website.
Do
If you build a desktop or phone app, ask for less on the first connection than the website would: no standing allowance until the person has used the app and come back to it.
Websites on a computer
The site talks to a wallet running on the same computer, such as BSV Desktop. Pressing Connect brings the wallet's window to the front with the request in it, and the person approves there.
The wallet has to be running. If it is installed but closed, the site sees the same thing as no wallet at all.
Do
When no wallet answers, say that the wallet may be closed as well as missing: "Open your BSV wallet, or install one, then try again."
Websites on a phone
A phone browser cannot reach a wallet. A BSV website works on a phone only when it is opened inside a wallet's built-in browser, such as BSV Browser, which passes the site's requests to the wallet beside it.
That makes the most common real failure easy to miss in testing: somebody taps a link in a message, it opens in Safari or Chrome, and Connect can do nothing.
Do
Detect the ordinary phone browser and say so before the person presses anything: "To pay here, open this page in your BSV wallet's browser." Offer to copy the link, and a way to install a wallet.
Don't
Show a Connect button on a phone browser that cannot connect, or an error only after it is pressed.
Everything that does not need the wallet should keep working in the ordinary browser: reading, browsing, prices. Only the steps that need the wallet should ask the person to move.
Desktop apps
A desktop app reaches the wallet the same way a website on a computer does, over a local connection to a wallet on the same machine, and the approval appears in the wallet's window. The difference is the name: the app gives its own, so the wallet's prompt cannot vouch for it (see Who is asking).
A desktop app can also keep running when its window is closed, which suits agents and recurring payments. That makes the limits and the off switch more important, not less. See Letting an agent spend.
Phone apps
There is no standard way yet for a separate phone app to reach the wallet a person already has. The routes in use today are:
- Build it as a website and let it run inside the wallet's browser. This is the route the standard supports best, and the one the reference designs in this guide use.
- Pair with a phone wallet by QR code. The app shows a code, the person scans it with their wallet, and requests travel between the two over a relay. Some BSV apps ship this today; it is a library choice, not part of the standard.
- Hold a wallet inside the app. Then the app is a wallet, and it takes on everything in the daily spending wallet, including backup and recovery.
Whichever route, the approval happens in a different app from the one the person started in, so the return trip is part of the design.
Do
Show what the person is waiting for while the approval is in another app or on another device, and bring them back to the exact step they left.
Don't
Treat leaving for the wallet as cancelling. A person who switches to approve and comes back should find the request still waiting, not a reset form.
Choosing a platform
If the product's job is a few payments or a sign-in, a website opened inside the wallet's browser gives the strongest identity check and the least to build. A desktop app earns its keep when it has to run unattended. A phone app that is not a wallet has the weakest route today, so choose it for reasons other than the wallet connection.
Open questions
- Will the wallets offer a standard way for a separate phone app to send requests, such as a link the wallet opens, and how would the wallet check that app's name?
- Should a wallet let a person mark an installed app's name as verified, and what would they be verifying it against?
- How do people react to "this name has not been checked" on a prompt for an app they just installed on purpose?
- Does a relay pairing feel like connecting, or like signing in on another device?
Related
- Connecting a wallet: what to ask for once connected
- Permissions and allowances: the prompt, allowances and revoking
- Errors and failed payments: no wallet installed, and the rest
- Letting an agent spend: apps that keep running
- Connected web app and Pay-per-use reader: reference designs built as websites
Written from: BRC-100, BRC-151, @bsv/sdk 4.0 WalletClient, @bsv/wallet-toolbox, Connecting a wallet.
Checklist
The rules on this page, in a form you can work through.
8 rules