React (Web)

This guide helps you integrate Passbase onto your website

General

Before integrating Passbase, you need to sign up on our developer dashboard. Integration of the Passbase Web Package follows a few simple steps:

  1. Install the Package through npm or yarn

  2. Get an API key from our developer platform

  3. Render a Passbase verification button and handle the result

Additionally, a non package manager dependent solution, with a HTML script tag can be found in the Web section.

1. Install the Package

You can use npm or yarn to install the package to your project.

# NPM
npm install --save @passbase/button
# Yarn
yarn add @passbase/button

You have successfully installed the Passbase button. 🎉

2. Get an API Key

Passbase uses API keys to allow access to the package and to route it back to your dashboard. Please use your publishable API key from your developer dashboard's API settings. If you don't have a developer account yet, you can create one using our developer dashboard.

Please use the publishable API key for all integrations. The secret key should never be exposed or used in a web integration or mobile app since it can access sensitive user data, if leaked!

3. Render the Verification Button

Import the Passbase Package at the Top

import Passbase from "@passbase/button";

The package supports UMD modules. Below, we'll present the ES import method.

Render a Button

There are two ways to add a Passbase verification button to your project:

1. As a React Component

To render the component provided by the Passbase package, you'll also need to install the peer dependencies that the component is leveraging. Please run the following command in your terminal:

npm install --save react-dom styled-components

Now, use the below to import the Verify button and add it to your view:

import React from 'react';
import './App.css';
import Passbase from "@passbase/button";
import VerifyButton from "@passbase/button/react";
function App() {
return (
<div className="App">
<header className="App-header">
<VerifyButton
apiKey={"YOUR_PUBLISHABLE_API_KEY"}
onFinished={(error, authKey, additionalAttributes) => {}}
additionalAttributes={{ }}
prefillAttributes={{ }}
theme={{ }}
/>;
</header>
</div>
);
}
export default App;

The table below gives an overview of all of the attributes of the component:

Attribute

Description

onFinished

The callback which will be called on completion, (error, authKey, additionalAttributes) => void

apiKey

The Passbase API Key you obtained from the dashboard.

additionalAttributes

Not required - an object containing attributes that will be stored and retrieved.

prefillAttributes

Not required - an object containing attributes used for form prefilling on the button

theme

not required - an object containing attributes used for the button's them

2. With a function

Another way to render the Passbase button is invoking it via a rendering function.

renderButton(mountingElement, cb, apiKey, (options = {}));

The table below gives an overview of all attributes of the component:

Attribute

Description

mountingElement

The DOM element that you want to mount the button on

cb

The callback, which will be called on completion, (error, authKey, additionalAttributes) => void

apiKey

The Passbase API Key you obtained from the dashboard

options

Not required

And..that's it! The button should now render.

4. Customizations

You can customize the appearance of the button and verification flow, by setting the prefillAttributes or the theme attribute. You can also pass additional attributes or values to our verification dashboard.

Changes in Verification Flow

If you set the prefillAttributes, you can skip certain steps in the process. Fields will already be selected or filled when the user navigates to a particular screen. So far, the following changes are available:

Attribute

Description

email

If you prefill email, the user's email address will automatically populate the field.

country

If you prefill country, the country will be listed at the top in the, "select identity document" dropdown menu.

prefillAttributes={{
email: "user@test.com",
country: "de"
}}

UI Customizations

If you set the theme attribute, you can change color or font within the verification flow. So far the following are available:

Attribute

Description

accentColor

This is the main color used for the progress bar as well as the buttons inside the flow

font

This is the font used within the verification flow

darkMode

A boolean that says if the whole UI should be dark.

theme={{
accentColor: "#ff0000",
font: "Fira",
darkMode: false
}}
A customized UI in darkmode

Additional Attributes

You can pass additional attributes along with the additionalAttributes object (e.g. additionalAttributes: ["userId":"a2ab4-f2jc4-k2dd4-1fa3x"]). This is useful if you want to pass an internal user ID, identifiers or other information to our dashboard. For instance, a user might have multiple email addresses they want to use over the lifetime on your platform. With this field, you'll be able to link all verifications back to that same user.

A full example with UI customizations, changes in the flow and additional attributes can be found below:

import React from 'react';
import './App.css';
import Passbase from "@passbase/button";
import VerifyButton from "@passbase/button/react";
function App() {
return (
<div className="App">
<header className="App-header">
<VerifyButton
apiKey={"YOUR_PUBLISHABLE_API_KEY"}
onFinished={(error, authKey, additionalAttributes) => {}}
additionalAttributes={{
customer_user_id: "a2ab4-f2jc4-k2dd4-1fa3x",
another_attribute: ""
}}
prefillAttributes={{
email: "user@test.com",
country: "de"
}}
theme={{
accentColor: "#ff0000",
font: "Fira",
darkMode: false
}}
/>;
</header>
</div>
);
}
export default App;

5. Handling Verifications

A verification is an asynchronous process that gives you a callback based result. The callback method gives you the ability to react if a user verification is finished or was canceled. e.g. bring the user to another screen or show an alert.

You can also use callbacks to check if a verification was completed or cancelled. Inside the callback method, you get the authKeyback. This key allows you to ping our API for the status of a verification e.g. if it was approved or rejected by our system. It might take a few minutes until a verification is fully processed. Of course, this also depends on if you approve or reject it in your dashboard.

Example & Demo App

The code below is an implementation of a sample class, with prefilled email, additional attributes and a UI customization.

You can find a complete sample app with on our Github page.

Passbase React Web Demo App

import React from 'react';
import './App.css';
import Passbase from "@passbase/button";
import VerifyButton from "@passbase/button/react";
function App() {
return (
<div className="App">
<header className="App-header">
{/* Without customizations */}
<VerifyButton
apiKey={"YOUR_PUBLISHABLE_API_KEY"}
onFinished={(error, authKey, additionalAttributes) => {}}
additionalAttributes={{ }}
prefillAttributes={{ }}
theme={{ }}
/>;
{/* With customizations */}
{/*
<VerifyButton
apiKey={"YOUR_PUBLISHABLE_API_KEY"}
onFinished={(error, authKey, additionalAttributes) => {}}
additionalAttributes={{
customer_user_id: "a2ab4-f2jc4-k2dd4-1fa3x",
another_attribute: ""
}}
prefillAttributes={{
email: "user@test.com",
country: "de"
}}
theme={{
accentColor: "#ff0000",
font: "Exo",
darkMode: true
}}
/>;
*/}
</header>
</div>
);
}
export default App;

You have successfully finished the Passbase React Integration! 🎉