Skip to content

Quick Start

Use this guide to integrate Web3 apps with the Arcana Auth SDK and quickly build the following features:

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:

  1. Use the Arcana Developer Dashboard and register the app; obtain a unique Client ID.
  2. Set up social providers that will be enabled for onboarding app users.
  3. 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.
  4. Allow authenticated users to instantly access the Arcana wallet.
  5. Add code in the app for programmatically accessing Web3 wallet operations supported by the Arcana wallet.

uth Usage Overview Auth Usage Overview

Arcana Auth SDK: auth, auth-react, auth-wagmi and auth-web3-reactpackages

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 the auth package and use the AuthProvider 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 the auth-react package for simple React apps. Initialize the AuthProvider and then use it to instantiate ProviderAuth. 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 the auth and the auth-web3-react packages. After installing, integrate the apps by initializing the AuthProvider first and then using it to create an ArcanaConnector 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:

  1. 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.

  2. 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:

  1. See how to integrate an app with the Arcana Auth SDK and create a Web2-like familiar user onboarding experience via Google , passwordless login.

  2. Manage Web3 user experience for signing blockchain transactions with the Arcana wallet:

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


Last update: May 25, 2023 by shaloo, shalz