Quick Start
Use this guide to integrate Web3 apps with the Arcana Auth SDK and quickly build the following features:
- Onboard users easily by configuring one or more authentication mechanisms
- Enable Arcana wallet and allow authenticated users to sign blockchain transactions, manage crypto assets, and more.
Already using Auth?
Arcana Auth SDK v1.0.3 -> v1.0.4: Follow the instructions in the Migration Guide and upgrade easily!
Earlier Arcana Auth SDK versions < v1.0.3: Note that there may be breaking changes that require you to reconfigure your app and also update the integration code. For more information, see archives for Migration Guides and Release Notes.
Overview
Follow these steps to register, configure, integrate, and use the Arcana Auth SDK features such as onboarding users and allowing them to sign blockchain transactions in Web3 apps:
- Use the Arcana Developer Dashboard and register the app; obtain a unique Client ID.
- Set up social providers that will be enabled for onboarding app users.
- Install and integrate the app with the Arcana Auth SDK and onboard users either via the built-in plug-and-play login UI or custom UI.
- Allow authenticated users to instantly access the Arcana wallet.
- Add code in the app for programmatically accessing Web3 wallet operations supported by the Arcana wallet.
Arcana Auth SDK: auth
, auth-react
, auth-wagmi
and auth-web3-react
packages
Depending upon the type of Web3 app, developers may need to integrate with one or more Arcana Auth packages:
-
To integrate vanilla HTML/CSS/JS apps with
Arcana Auth SDK
, install theauth
package and use theAuthProvider
to access the standard Ethereum provider exposed for blockchain transactions. For details, see Arcana Auth SDK Usage Guide. -
In addition to the
auth
package, also use theauth-react
package for simple React apps. Initialize theAuthProvider
and then use it to instantiateProviderAuth
. For details, see React App Integration Example. -
For Web3 apps using wallet connector frameworks such as Wagmi and RainbowKit, use the
auth
and theauth-wagmi
packages. For the Web3-React wallet connector framework, use theauth
and theauth-web3-react
packages. After installing, integrate the apps by initializing theAuthProvider
first and then using it to create anArcanaConnector
that is used to initialize the respective wallet connector framework. For details, see Wagmi example, RainbowKit example and Web3-React example.
Register & Configure
First, follow the instructions to register and configure the app using the Arcana Developer Dashboard. As part of the app registration, a unique value, Client ID, is assigned to each app. This is required for integrating the app with the Arcana Auth SDK.
During app configuration, developers can enable one or more options to onboard app users.
User Onboarding Options
Web3 app developers can configure one or more authentication providers to let app users choose one of the available options and log in.
If the app is registered but none of the supported authentication providers are enabled and configured for user onboarding, then by default, only the passwordless login can be used to onboard app users.
Install Arcana Auth SDK
npm
npm install --save @arcana/auth
yarn
yarn add @arcana/auth
CDN
<script src="https://cdn.jsdelivr.net/npm/@arcana/auth"></script>
<script src="https://unpkg.com/@arcana/auth"></script>
Integrate App
Follow these instructions and integrate the app with the Arcana Auth SDK. Manage user experience for signing blockchain transactions with wallet visibility settings. These must be specified during app integration and instantiation of the AuthProvider
.
After integrating with the Arcana Auth SDK app developers can use the AuthProvider
to access the standard Ethereum Web3 provider interface in the context of an authenticated user. Use AuthProvider
functions to onboard users, and sign blockchain transactions. For more information, see Arcana Auth SDK Usage Guide and Arcana Auth SDK Reference Guide, and the Arcana wallet Developer's Guide.
Onboard Users
After installing and integrating with the Arcana Auth SDK, app developers can add code to onboard the users. There are two ways to build user onboarding in the app:
-
Use the plug-and-play feature of Arcana Auth SDK to instantly access the built-in, default pop-up user login interface. No need to build any user login UI in the app. Simply add code asking the user to log in and call the plug-and-play function of the
AuthProvider
. App users can log in by choosing one of the authentication mechanisms configured by the app developer, displayed in the plug-and-play pop-up UI. -
Build a custom user login UI for the app and call the appropriate Arcana Auth SDK functions for onboarding users via the configured social providers and the passwordless login option.
Sign Blockchain Transactions
After onboarding users, developers can add code to use the AuthProvider
in the app and call standard JSON RPC Web3 wallet functions programmatically in the context of an authenticated user. Enable authenticated users to sign blockchain transactions, send and receive tokens, NFTs, and more using the Arcana wallet.
Deploy App
An app integrated with the Arcana Auth SDK can be deployed for use only after the developer has completed these steps:
- Register and configure the app via the Arcana Developer Dashboard
- Integrate the app with the Arcana Auth SDK
- Add code to onboard users
- Add code to allow authenticated users to sign the blockchain transactions
Developers can choose to deploy one instance of the app (say, under active development) on the Arcana Testnet while simultaneously deploying a stable version of their app (say, one validated on Testnet and ready for users) on the Arcana Mainnet.
By default, when an app is registered, a 'Testnet' configuration profile is associated with the app, and a unique Client ID is assigned to this 'Testnet' profile. To deploy your app on the Arcana Mainnet, you need to create a corresponding 'Mainnet' configuration profile and update the Arcana Auth SDK integration code to use the new Client ID assigned to the app's 'Mainnet' configuration profile. For details on how to deploy your app on the Arcana Testnet / Mainnet, see App Deployment Guide.
Examples
Here are some examples of Arcana Auth SDK usage:
-
See how to integrate an app with the Arcana Auth SDK and create a Web2-like familiar user onboarding experience via Google , passwordless login.
-
Manage Web3 user experience for signing blockchain transactions with the Arcana wallet:
- Enable authenticated users to sign blockchain transactions by setting the Arcana wallet visibility parameter while instantiating the
AuthProvider
. - Use pre-configured blockchains or add other supported blockchain networks programmatically as per your app requirements. Refer to the list of supported blockchain networks.
- Allow authenticated app users to use the Arcana wallet and check account balances, send or receive ERC-20, ERC-721, and ERC-1155 tokens, deploy smart contracts, interact with smart contracts, switch networks, manage NFTs. See the Arcana wallet Developer's Guide.
- Enable authenticated users to sign blockchain transactions by setting the Arcana wallet visibility parameter while instantiating the
Developer & User Guides
For more details on how users interact with the Arcana wallet, see Arcana wallet User Guide.
Developers can refer to the Arcana Developer Dashboard User Guide to learn more about how to register and configure the apps. Also, see Arcana Auth SDK Usage Guide and the Arcana Auth SDK Reference Guide for various functions offered by the Arcana Auth SDK. To programmatically access Web3 wallet operations, see Arcana wallet Developer's Guide.
Release Details
Refer to the Release Notes to see what's changed in the latest version.
You can also watch GitHub releases to receive notifications when a new release for the Arcana Auth SDK is published.
See also
- User Authentication
- Video Tutorials
- Configuring Arcana wallet visibility
- Handling Arcana Auth SDK error messages
- Arcana Auth SDK Usage Guide
- Arcana Auth SDK Reference Guide