Civic Developer Hub

Gateway Provider

The GatewayProvider is a React component that enables your dApp frontend to
  • access all available information of your user's Civic Pass
  • trigger the issuance of a new Civic Pass
There are only minimal differences in the way the GatewayProvider is configured for each supported chain. Once configured, using it is chain-agnostic! In this section we will go through the steps required to integrate the GatewayProvider into your UI, regardless of which chain your dApp supports.

1. Install the React component for your chain

First, install the Civic Gateway library for your chain.
Ethereum / Polygon
npm i @civic/[email protected]
npm i @civic/[email protected]

2. Import and configure the Gateway Provider

Once the Gateway React library is installed, import and configure the GatewayProvider component.
The required configuration properties vary slightly depending on the target chain. You can find the details on the configuration properties of each chain here.
Ethereum / Polygon
import { GatewayProvider } from "@civic/solana-gateway-react";
import { Connection, clusterApiUrl } from '@solana/web3.js';
connection={new Connection(clusterApiUrl("mainnet-beta"))}
import { GatewayProvider } from "@civic/ethereum-gateway-react";
Children wrapped by this GatewayProvider will have access to the connected wallet's Civic Pass.
It's suggested to place the <GatewayProvider> as high up in the component tree as possible, to ensure you have access to the Civic Pass state is available throughout your dApp.

3. Use the useGateway hook to interact with a Civic Pass

You can also use the provided Identity Button reference implementation to handle everything described in this section.
Now that you have initialised the GatewayProvider context, you can use the included useGateway hook to
  • trigger the issuance of a new Civic Pass modal
  • access the state of the Civic Pass
Ethereum / Polygon
import { useGateway } from "@civic/solana-gateway-react";
import { useGateway } from "@civic/ethereum-gateway-react";

Trigger the issuance of a Civic Pass

Calling the function requestGatewayToken opens the modal dialog, which will then guide the user through the flow of collecting and verifying the users information. The information collected varies depending on the configured Gatekeeper Network.
const { requestGatewayToken } = useGateway()
<button onclick={requestGatewayToken}>Civic Pass</button>
For example, this is the initial screen your users will see when issuing a Captcha Verification Civic Pass:
Even if the user already has a Civic Pass, you don't have to worry about enabling/disabling your button. The Civic Pass modal supports being triggered for any possible Civic Pass status and will always display the correct screen that corresponds that Civic Pass status.
For example, if the the user already has a Civic Pass, triggering the modal again via requestGatewayToken displays the following screen:

Access the state of the Civic Pass

All children of the GatewayProvider have access to the user's Civic Pass state via the useGateway function.
const { gatewayStatus, gatewayToken } = useGateway();
The gatewayStatus indicates the overall status of the Civic Pass and should be displayed in your dApp. Either via custom UI or by simply integration the Civic Identity Button included with the library. Of course you are free to update your UI depending on the status as you see fit.
The gatewayToken represents the on-chain structure of the Civic Pass. This will is only defined if the Civic Pass is ACTIVE.
If the token does not exist or is in a non-active state (e.g. Frozen), this state variable will be undefined . The dApp should disable certain parts of the UI when gatewayToken is undefined to prevent dApp usage. This only complements the on-chain check and does not replace it.

3. Add the Identity Button

To expose the status of the user's Civic Pass in your UI, simply add the Identity Button component (also included in the Gateway library) , by placing it inside the <GatewayProvider> context you created in the previous step.
import IdentityButton from '@civic/solana-gateway-react';
<IdentityButton />
import IdentityButton from '@civic/ethereum-gateway-react';
<IdentityButton />
Besides just displaying the Civic Pass status, users can also start the issuance of their Civic Pass, should they not already have one. The Identity Button is automatically updated to display the corresponding Civic Pass status.