Custom Login UI

With Wagmi, Web3 developers can allow app users to easily switch between multiple wallets within a single application. Wagmi apps can use the custom connector offered by the Arcana Auth SDK to enable the Arcana wallet.

In this guide, you will learn how to onboard users via a custom login UI in Wagmi apps integrated with the Arcana Auth SDK.

Prerequisites

Register Web3 Application: Log into the Arcana Developer Dashboard https://dashboard.arcana.network to register and configure the app before they can use the Arcana Auth SDK and enable the Arcana wallet for authenticated app users.
Set up Authentication Providers: Click on the Social Auth tab in the Arcana Developer Dashboard. Configure and select one or more supported authentication providers for onboarding the app users.

Configure Authentication Providers

You may be required to configure additional provider details for different authentication providers. In the case of Google, the developer must use Google Developer Console to set up the app and generate a Google assigned client ID for Google OAuth. This Google ClientID will be configured in the Arcana Developer Dashboard Social Auth settings before integrating the app.

For details, see how to configure authentication providers.
Save the Client ID assigned to the app and displayed in the Arcana Developer Dashboard. It is required later during integrating with the Arcana Auth SDK.

Steps

Onboarding users in Web3 Wagmi apps via custom login UI powered by the Arcana Auth SDK is simple!

Follow these three steps:

Step 1: Install Arcana Auth SDK packages

npmyarnCDN

npm install --save @arcana/auth-wagmi @arcana/auth

yarn add @arcana/auth-wagmi @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-wagmi"></script>
<script src="https://unpkg.com/@arcana/auth-wagmi"></script>

Step 2: Create `AuthProvider` and `ArcanaConnector`

Import auth and auth-wagmi packages. First create an AuthProvider by specifying the unique Client ID value assigned to the app after registering it through the Arcana Developer Dashboard.

Next, create the ArcanaConnector and specify the AuthProvider.

If the custom login UI is configured such that it allows a single authentication provider to onboard users, developers can specify the provider as an additional parameter while creating the ArcanaConnector. Otherwise, if the custom login UI offers multiple authentication provider options then developers can create a single ArcanaConnector without specifying the authentication provider and later call the setLogin function for the selected provider, in response to the user's onboarding choice.

Configure Authentication Providers before ArcanaConnector creation

To build a custom login UI, developers can choose from the list of supported authentication providers or use passwordless. Wire the UI buttons for onboarding via different options to the setLogin function of the ArcanaConnector.

Enable Authentication Provider

auth-wagmi-example/utils/wagmi_client.js

import { AuthProvider } from "@arcana/auth";
import { ArcanaConnector } from "@arcana/auth-wagmi";
import { polygon, polygonMumbai } from "wagmi/chains";
import { configureChains, createClient, Chain } from "wagmi";
import { publicProvider } from "wagmi/providers/public";

/* Using Custom UI for user login via Google */
const auth = new AuthProvider(`${arcana_client_id}`) // Singleton
export const connector = (chains: Chain[]) => {
  return new ArcanaConnector({
    chains,
    options: {
      auth: auth,        
      login:  {
          provider: 'google', //See 'Custom Login UI' section in the documentation for other supported providers.
        } // Optional, specify here during ArcanaConnector instantiation or in the setLogin function
    },
  });
};

// Custom UI Alternative 
// Use setLogin function after creating the connector.

/*
const auth = new AuthProvider(`${arcana_client_id}`) // Singleton
export const connector = (chains: Chain[]) => {
  return new ArcanaConnector({
    chains,
    options: {
      auth: auth             
    },
  });
};

connector.setLogin({
  provider: 'google'
})
*/

...

Enable Passwordless Login

auth-wagmi-example/utils/wagmi_client.ts

import { AuthProvider } from "@arcana/auth";
import { ArcanaConnector } from "@arcana/auth-wagmi";
import { polygon, polygonMumbai } from "wagmi/chains";
import { configureChains, createClient, Chain } from "wagmi";
import { publicProvider } from "wagmi/providers/public";

/* Using Custom UI for Passwordless user login */
const auth = new AuthProvider(`${arcana_client_id}`) // Singleton
export const connector = (chains: Chain[]) => {
  return new ArcanaConnector({
    chains,
    options: {
      auth: auth,        
      login:  {
          provider: 'passwordless', 
          email: 'abc@example.com' //optional
        } // Optional, specify login details here or during ArcanaConnector instantiation or in the setLogin function
    },
  });
};

// Custom UI Alternative 
// Use setLogin function after creating the connector.

/*
const auth = new AuthProvider(`${arcana_client_id}`) // Singleton
export const connector = (chains: Chain[]) => {
  return new ArcanaConnector({
    chains,
    options: {
      auth: auth             
    },
  });
};

connector.setLogin({
  provider: 'passwordless',
  email: 'abc@example.com' //optional
})
*/

...

Step 3: Set up WagmiConfig

Next, provide the newly instantiated and configured ArcanaConnector to set up Wagmi:

auth-wagmi version < v2.0.0auth-wagmi version > v2.0.0

App.js

// Note:  
// This sample code is for 
// wagmi versions <1.x.x and auth-wagmi <2.0.0

import { WagmiConfig, configureChains, createClient, Chain } from "wagmi";
import { goerli, mainnet, polygon, polygonMumbai } from "wagmi/chains";
import { InjectedConnector } from "wagmi/connectors/injected";
import { publicProvider } from "wagmi/providers/public";
import { ArcanaConnector } from "@arcana/auth-wagmi";
import { newAuthProvider } from "../utils/newArcanaAuth";

import "../styles/globals.css";
import type { AppProps } from "next/app";

const { chains, provider, webSocketProvider } = configureChains(
  [mainnet, goerli, polygon, polygonMumbai],
  [publicProvider()],
  { targetQuorum: 1 }
);

const connectors = [
  new ArcanaConnector({
    chains,
    options: {
      auth: newAuthProvider(),
      login: {
        provider: "google",
      },
    },
  }),
  new InjectedConnector({
    chains,
    options: {
      name: "Browser Wallet",
      shimDisconnect: true,
    },
  }),
];

const wagmiEntity = createClient({
  autoConnect: true,
  connectors,
  provider,
  webSocketProvider,
});
...

App.js

// Note:  
// This sample code is for 
// wagmi versions 1.x.x and auth-wagmi 2.0.0
import { configureChains, createConfig, WagmiConfig } from "wagmi";
import { publicProvider } from "wagmi/providers/public";
import { ArcanaConnector } from "@arcana/auth-wagmi";
import { polygon, polygonMumbai } from "wagmi/chains";
import { newAuthProvider } from "./utils/newArcanaAuth";
import { useAccount, useConnect, useDisconnect, useBalance } from 'wagmi'
import "../styles/globals.css";

const { chains, provider, webSocketProvider } = configureChains(
  [mainnet, polygon, polygonMumbai],
  [publicProvider()],
  { targetQuorum: 1 }
);

export const connector = (chains: Chain[]) => {
  return new ArcanaConnector({
    chains,
    options: {
      auth: newAuthProvider(),
      login: {
        provider: "google",
      },
    },
  });
};

const { chains, publicClient } = configureChains(
  [polygon, polygonMumbai],
  [publicProvider()]
);

export const wagmiEntity = createConfig({
  autoConnect: true,
  connectors: [connector(chains)],
  publicClient,
});
...

Wagmi createClient and configClient

For more details on the createClient and configClient functions of the Wagmi package, see Wagmi Getting Started Guide and Wagmi 1.x.y Migration Guide.

Use the WagmiConfig component in the _app.js file.

auth-wagmi version < v2.0.0auth-wagmi version > v2.0.0

app.tsx

function App({ Component, pageProps }: AppProps) {
  return (
    <WagmiConfig client={wagmiEntity}>
      <Component {...pageProps} />
    </WagmiConfig>
  );
}

app.tsx

function App({ Component, pageProps }: AppProps) {
  return (
    <WagmiConfig config={wagmiEntity}>
      <Component {...pageProps} />
    </WagmiConfig>
  );
}

Here is an example of how you can layout the wagmiClient with the Arcana wallet configured as the wallet option on the app page. Note that in this example, the setLogin function is used after creating the wallet connector when the user chooses the configured provider:

auth-wagmi-example/pages/index.tsx

import { ArcanaConnector } from "@arcana/auth-wagmi";
import { useEffect, useState } from "react";
import { useAccount, useConnect } from "wagmi";

export default function Home() {
  const { connect, connectors, error, isLoading, pendingConnector } =
    useConnect();
  const { connector, address, isConnected, status } = useAccount();

  const [isMounted, setIsMounted] = useState(false);

  useEffect(() => {
    setIsMounted(true);
  }, []);

  if (!isMounted) {
    return <></>;
  }
  if (isConnected) {
    return (
      <div className="main">
        <div className="connected-msg">
          Connected to {connector?.name} with address {address}
        </div>
      </div>
    );
  } else {
    return (
      <div className="main">
        <div>
          {!isConnected &&
            connectors.map((connector) => (
              <>
                <button
                  className="connect-btn"
                  key={connector.id}
                  onClick={() => connect({ connector })}
                >
                  Connect to {connector.name}
                  {isLoading &&
                    pendingConnector?.id === connector.id &&
                    " (connecting)"}
                </button>
                <div>
                  <button
                    className="connect-btn"
                    key={connector.id}
                    onClick={() => {
                      if (connector.id == "arcana") {
                        (connector as ArcanaConnector).setLogin({
                          provider: "google",
                        });
                      }
                      connect({ connector });
                    }}
                  >
                    Connect to {connector.name} (google)
                    {isLoading &&
                      pendingConnector?.id === connector.id &&
                      " (connecting)"}
                  </button>
                </div>
              </>
            ))}
        </div>
        {error && <div className="error-box">{error.message}</div>}
      </div>
    );
  }
}

That is all!

The Web3 Wagmi app can now onboard users using the custom login UI. Authenticated users can instantly access the Arcana wallet and sign blockchain transactions.

Example: Sample Wagmi App

See sample Wagmi app for details.

What's Next?

After integrating and onboarding users in the Web3 app developers can add code programmatically and enable Web3 wallet operations in the authenticated user's context.