YOU ARE: A web frontend or full-stack dApp developer
YOU’RE BUILDING: A Radix dApp website
THE PROBLEM TO SOLVE: How to use the √ Connect button on your website to make sure Radix users can instantly recognize your website as a Radix dApp where they know how to connect their Radix Wallet and interact with confidence.
THE TOOL TO USE: Radix dApp Toolkit and its √ Connect button
Background
The root of the Web3 concept is an internet with a revolutionary new capability: user-controlled digital assets and identity. Blockchain made this possible at a technology level, but the world has been in search of the right new Web3 UX paradigm. Early crypto wallets let users control their own assets, but had no good way of connecting them to websites and applications. Metamask made it possible for a user’s account to directly interact with a website by sharing an address and receiving transaction requests, but the user interface was clunky and limiting. So what’s the right approach?
The core idea of Web3 should be that a user owns their digital assets and identities in their own digital wallet – even when not using any particular application. And when the user does connect to an application, they can choose who they want to be and what they want to bring with them on that particular app or website.
The Radix Network and Radix Wallet are designed to make exactly that not just possible but frictionless and intuitive. The wallet itself, however, is only one part of the user’s Web3 experience.
The Radix Wallet is the user’s trusted protector and manager of their assets and identities – enabling easy passwordless logins with Personas, easy sharing of accounts and other personal data with the user’s permission, and giving the user control of transactions that touch the things they own.
But it is your dApp that defines a useful and deep Web3 user experience that those assets and identities can interact with. In the end, they are typically using a website that you create, and it is the job of the Radix Wallet to “get out of the way” and simply make it easy for the user to choose who they want to be and what they want to bring with them when they enter your world.
The Problem
To build a great Web3 UX, there is a crucial connection between your website and the Radix Wallet that must have its own UI element for the user. Today’s typical “Connect Metamask” button is an example, but we want something better.
The user needs a few things to make this dApp/wallet connection understandable and useful:
- To instantly recognize that this is a place where they can connect their Radix Wallet
- To immediately know how to connect their Radix Wallet and log in using a Persona
- To see that they are logged in, and what Persona they’re logged in as
- To see what they are sharing (whether accounts or other personal data) with that particular dApp website
- To be able to update what they share with that dApp website, or choose to log out if they wish
- To see when requests to their wallet are pending
These are really the “basics” of meaningfully connecting your assets and identities to a Web3 website on Radix. These things have nothing to do with the dApp’s own functionality – they’re just the universal things that define being a Web3 user on Radix that every user will expect on every dApp website.
However, if every website does these common things in a different way, users are likely to lose patience before they even start. If the way of doing them looks different on every website, users will spend more effort identifying where to go and will be unsure if it acts the same way as on another website.
But if the way of doing these things is recognizable, friendly, and consistent across every dApp website built on Radix that they use, it makes all of those dApps more appealing, trustworthy, and frictionless to use – a rising tide that lifts all boats.
The Radix Tool for the Job
Effectively, users would like there to be a sort of “representative” of their own Radix Wallet on every website they connect to. It should be a simple UI element that they can immediately recognize like a good friend, and know that it will always give them “the basics” of bringing their identities and assets to websites using the Radix Wallet.
The Radix dApp Toolkit (RDT) provides exactly that. RDT is a typescript library that provides a collection of common dApp frontend functionality. It makes it easy to do the basics: request Persona logins, request account and data, request transactions, handle user data caching, manage browser sessions, and more.
Specifically when it comes to UX, RDT comes with a visual element – a √ Connect button – that you place on your dApp website and provides that simple visual “representative” of the user’s own wallet there.
The √ Connect button includes its own user menu that gives users a clear view on what they have brought with them from their Radix Wallet to this dApp, a history of requests to their wallet, the ability to update what they are sharing, and to log out.
The Recommended Use Pattern
As a developer, you need only import RDT, place the √ Connect button in your website layout, and set a few options. RDT will automatically ensure that the button and its menu are populated with the correct information based on your dApp’s usage of RDT’s wallet request and session management features. Basically, the button shows whatever your dApp has received from that user’s wallet, including Persona status, ongoing data sharing permissions, and ongoing account information permissions.
√ Connect button appearance
The first thing that is important about the √ Connect button is simply that it is consistently recognizable. It’s similar in concept to single-sign-on buttons from Google, Facebook, and others. These companies provide strict guidelines for how their sign-in button looks, specifically so that users can always recognize it at a glance. This typically includes consistent font, color options, and logo usage – with a little flexibility to accommodate different website styles
For example, here’s part of Google’s guidelines for their “Sign on with Google” button:
Similarly, the √ Connect button includes quite a bit of customizability that you can take advantage of when configuring RDT for your website, while still maintaining the consistency to give your users a smooth and familiar experience.
Customization options include:
- Selection of colorways for “not connected” state
- Light or dark presentation for the menu
- Button width and height, with a minimized no-text button mode for very small desired widths
- Button corner radius
In fact, you can play around with the appearance customization options using Storybook here.
√ Connect button logged in/out state
RDT makes it easy to manage if the user is logged in/out and to show them that state with the √ Connect button and its menu.
By default, if a user clicks “Connect” and chooses a Persona in their wallet to login with, they are automatically considered logged in and the button updates its state to match. That done, your dApp can get that Persona ID and any data requested from the user. RDT creates a browser session, so that the user remains logged in even when refreshing the page or returning to it later. For a “pure frontend” dApp that has no backend server at all, this may be all that’s needed, and the UX is fully automated.
However, some dApps may need to do some amount of verification of a Persona login. Usually this would be a “full stack” dApp that has its own user database and uses ROLA to verify Persona logins. In this case, RDT can be configured to not automatically consider the user logged in, but instead wait for your dApp to confirm that its own verification logic has been satisfied and it is okay for them to be logged in. That done, the √ Connect button will update its state and your dApp may get Persona and other data from the wallet as usual.
In addition, your dApp may have its own logic to cause a user to be logged out (eg. by idle time). RDT may be told to disconnect a user, returning the button to its default state where the user may again try to connect – just as if they had clicked “Log Out” themselves.
√ Connect button “Update Data Sharing” feature
When a user is logged in, they may click “Update Data Sharing” in the √ Connect button’s menu to automatically send a special request to their wallet. This request repeats whatever ongoing data request your dApp has made, “resetting” those permissions so that the user is prompted in their Radix Wallet to make their selections again.
For example, if your dApp requires 1 or more account addresses, the user might have initially shared accounts A, B, and C. Perhaps later they added an account D to their wallet and also wish to share that with your dApp for use. Clicking “Update Data Sharing” will again ask them to choose 1 or more account addresses, and they may choose A, B, C, and D. This will update RDT’s cache of shared data so that you may refresh your dApp’s UI to comprehend the new sharing.
√ Connect button new Radix user onboarding
In many cases, your dApp will be the exciting thing that brings new users to Web3 and Radix for the first time! For these users, the √ Connect button may be their first touchpoint to get started. To help get these users smoothly onboarded, the √ Connect button automatically checks if the user has set up the Radix Wallet and Radix Connector browser extension.
If they haven’t, they will get some help with setting up, including getting them over to the official Radix Wallet download and setup page where they will be get their Radix Wallet and Radix Connector browser extension set up in a few clicks. From there, they can get straight back to connecting to and using your dApp.
Links to Get Started
