Skip to content

Quick Start: Web3-React Apps

Web3 apps using 'Web3-React' framework can easily onboard users via social login by integrating with the Arcana Auth Web3 React SDK!

Prerequisites

1. Register & Configure

2. Install SDKs

For 'Web3-React' app, install the following packages:

npm install --save @arcana/auth-web3-react @arcana/auth
yarn add @arcana/auth-web3-react @arcana/auth
<script src="https://cdn.jsdelivr.net/npm/@arcana/auth"></script>
<script src="https://unpkg.com/@arcana/auth"></script>
<script src="https://cdn.jsdelivr.net/npm/@arcana/auth-web3-react"></script>
<script src="https://unpkg.com/@arcana/auth-web3-react"></script>

Use latest SDKs

Use the latest Arcana Auth SDK release: v1.0.10. Migrate from Arcana Auth SDK v1.0.9 -> v1.0.10.

Versions older than Arcana Auth SDK v1.0.9 may encounter potential breaking changes that require app reconfiguration, integration code updates, and redeployment. Refer to the Migration Guides and Release Notes.

In addition to the latest Arcana Auth SDK, for Web3-React apps, you must also use the latest Arcana Auth Web3 React SDK release: v0.0.1

3. Integrate

Import AuthProvider from the auth package.

import { AuthProvider } from '@arcana/auth'

Create a new AuthProvider instance. Specify the unique Client ID obtained during the app registration.

const auth = new AuthProvider(
  "xar_test_445007f942xxxxxxxxxxxxxxxxxx484cAfd2", // App client ID
  { 
    position: 'left',         // default: right
    theme: 'light',           // default: dark
    alwaysVisible: false,     // default: true, wallet always visible
    setWindowProvider: true,  // default: false, window.ethereum not set
    connectOptions: {
      compact: true           // default: false, regular plug-and-play login UI
    },
    chainConfig: {
      chainId: '137',                    // defaults to Ethereum
      rpcUrl: 'https://polygon-rpc.com', // defaults to 'https://rpc.ankr.com/eth'
    },
})
AuthProvider Optional Parameters

Besides Client ID input parameter, you can optionally customize these settings in the AuthProvider constructor:


position: wallet position within the app context - left|right

theme: wallet theme - light|dark

connectOptions: built-in login UI compact mode - true|false


See AuthProvider constructor parameters for details.

Next, import the ArcanaConnector from the auth-web3-react package.

Initialize the ArcanaConnector by specifying the AuthProvider created earlier:

example/connectors/arcanaWallet.ts
import { initializeConnector } from "@web3-react/core";
import { ArcanaConnector } from "@arcana/auth-web3-react";
import { AuthProvider } from "@arcana/auth";
import { URLS } from "../chains";

const auth = new AuthProvider(
  "xar_test_b2ddexxxxxxxxxxxxxxxxxxxx8b1fa3f"
);
export const [arcanaConnect, hooks] = initializeConnector<ArcanaConnector>(
  (actions) =>
    new ArcanaConnector(auth, {
      actions,
    })
);
...

The app is now integrated with the Arcana Auth SDK and the Arcana Auth Web3 React SDK. Use React hooks to enable AuthProvider functions via the ArcanaConnector.

example/components/connectorCards/ArcanaConnectCard.tsx
import { useEffect, useState } from "react";

import { MAINNET_CHAINS } from "../../chains";
import { hooks, arcanaConnect } from "../../connectors/arcanaWallet";
import { Card } from "../Card";

const CHAIN_IDS = Object.keys(MAINNET_CHAINS).map(Number);

const {
  useChainId,
  useAccounts,
  useIsActivating,
  useIsActive,
  useProvider,
  useENSNames,
} = hooks;

export default function ArcanaConnectCard() {
  const chainId = useChainId();
  const accounts = useAccounts();
  const isActivating = useIsActivating();

  const isActive = useIsActive();

  const provider = useProvider();
  const ENSNames = useENSNames(provider);

  const [error, setError] = useState(undefined);

  // attempt to connect eagerly on mount
  useEffect(() => {
    arcanaConnect.connectEagerly().catch((error) => {
      console.debug("Failed to connect eagerly to arcanaConnect", error);
    });
  }, []);

  return (
    <Card
      connector={arcanaConnect}
      activeChainId={chainId}
      chainIds={CHAIN_IDS}
      isActivating={isActivating}
      isActive={isActive}
      error={error}
      setError={setError}
      accounts={accounts}
      provider={provider}
      ENSNames={ENSNames}
    />
  );
}

Onboard Users

example/connectors/arcanaWallet.ts
import { initializeConnector } from "@web3-react/core";
import { ArcanaConnector } from "@arcana/auth-web3-react";
import { AuthProvider } from "@arcana/auth";
import { URLS } from "../chains";

const auth = new AuthProvider(
  "xar_test_b2ddexxxxxxxxxxxxxxxxxxxx8b1fa3f"
);
export const [arcanaConnect, hooks] = initializeConnector<ArcanaConnector>(
  (actions) =>
    new ArcanaConnector(auth, {
      actions,
    })
);
...
Custom Login UI

You can onboard users through a custom login UI instead of the built-in plug-and-play one. See how to use custom login UI for onboarding users in a 'Web3-React' app for details.

Arcana JWT Token

Upon successful authentication, Arcana Auth SDK returns a unique JWT token to the app called the Arcana JWT Token. App developers can use this token to verify user login and subsequently generate another token for app use. Learn more about how to verify the Arcana JWT Token for apps deployed on Testnet and Mainnet.

Sign Transactions

Use the standard JSON RPC Web3 wallet operations supported by the AuthProvider. See Web3 Wallet Operations for details.

Wallet Customization

Besides theme and branding, developers can manage the user experience for signing blockchain transactions by choosing the default, built-in Arcana wallet UI and tinkering with the wallet visibility or selecting a custom wallet UI.

4. Deploy

That's all!

Your 'Web3-React' app is now powered by Arcana Auth SDK and Arcana Auth Web3 React SDK to onboard users via social login and sign blockchain transactions using Arcana wallet.

See Also

Arcana Auth SDK Quicklinks


Last update: April 12, 2024 by shaloo