Skip to main content

React Web SDK

This is a lightweight React library that allows a web client to display and send

A request (or presentation request) is a request for a presentation. It's sent by a company to a user, who chooses whether to share a presentation in response.
Example: Hooli FinTech sends Richard a request for (a presentation of) a KYC verification credential from ACME Bank.
Components: A company creates requests using the Server SDK and routes them to users using the Web SDK. A user's app responds to requests using the Mobile SDK.
requests to users, who can respond with
A presentation is a set of one or more credentials. It's shared with (or presented to) a company by a user.
Example: Richard shares a presentation of a KYC verification credential (which ACME Bank issued to him) with Hooli FinTech.
Components: A user's app shares (or presents) presentations using the Mobile SDK, and a company verifies presentations using the Server SDK.
presentations.

note

Please contact us for frameworks other than React.

Overview

Minimum Requirements

  • React v16.8.0 and above
  • English language (internationalization coming soon)

TypeScript Support

The SDK is written in TypeScript and exports relevant types. Some types are pulled from our shared types library, @unumid/types. We recommend adding @unumid/types as a dependency to ensure full type support between this React Web SDK and the Server SDK.

Installation

The React Web SDK is available via package managers NPM/Yarn or via the open source Github repo.

npm install @unumid/web-sdk-react

Alternatively, you can install it directly from Github.

npm install @unumid/web-sdk-react@https://github.com/UnumID/web-sdk-react.git

Functionality

Create PresentationRequests

By default, the SDK will create a PresentationRequest as soon as it is rendered. It will periodically regenerate the PresentationRequest (to ensure it doesn't expire) until the user shares data or declines the request, or the widget is unmounted.

tip

An Unum ID

A request (or presentation request) is a request for a presentation. It's sent by a company to a user, who chooses whether to share a presentation in response.
Example: Hooli FinTech sends Richard a request for (a presentation of) a KYC verification credential from ACME Bank.
Components: A company creates requests using the Server SDK and routes them to users using the Web SDK. A user's app responds to requests using the Mobile SDK.
request is what a company uses to request a
A presentation is a set of one or more credentials. It's shared with (or presented to) a company by a user.
Example: Richard shares a presentation of a KYC verification credential (which ACME Bank issued to him) with Hooli FinTech.
Components: A user's app shares (or presents) presentations using the Mobile SDK, and a company verifies presentations using the Server SDK.
presentation from a user. The request is represented in code as a PresentationRequest object.

You can use different combinations of props (see below) to choose how much control you want to have. For example, instead of automatically creating a PresentationRequest on load, you may want to trigger its creation based on a user interaction like a button click.

PresentationRequests are shared to an Unum ID-powered mobile app a user's device via deep links. The React Web SDK determines how it displays them based on the browser's userAgent.

Defaults

QR Code

On non-mobile browsers, the SDK will default to displaying the deep link as a QR code (which a user scans with their mobile device).

Button

On mobile browsers, the SDK will default to displaying the deep link as a button. Tapping the button opens the corresponding app on their device.

Fallbacks

In some situations, neither a QR code nor a button is convenient, so the SDK uses fallback options in this order:

  1. push notification
  2. SMS
  3. email

These are called fallbacks in part because they require some information about the user to work (unlike QR codes and buttons). To send push notifications, you need to provide a push notification identifier for the user, to send SMS messages, you need to provide a phone number for the user, and to send emails, you need to provide an email for the user.

You may have this information stored in your database, associated with the user. If so, you can ask them to log into your existing account system, retrieve the necessary information, and then use the fallbacks options described above. The SDK accepts a goToLogin prop for this purpose.

Push Notification

Sends a push notification to the user's device. Tapping the push notification will open the corresponding app on the user's device and prompt them to share (a

A presentation is a set of one or more credentials. It's shared with (or presented to) a company by a user.
Example: Richard shares a presentation of a KYC verification credential (which ACME Bank issued to him) with Hooli FinTech.
Components: A user's app shares (or presents) presentations using the Mobile SDK, and a company verifies presentations using the Server SDK.
presentation of) the requested
A credential is a collection of data about a person. It's issued by a company (i.e. created and sent to a user) and stored in the company's app, on that user's device.
Example: ACME Bank issues a KYC verification credential to Richard (an ACME user). This includes Richard's contact information and account numbers, as well as a level of confidence in the accuracy of the data.
Components: A company issues credentials using the Server SDK, and an app stores credentials using the Mobile SDK.
credentials.

In order to use this fallback, you will need to provide the userInfo prop with a pushToken field containing a push notification identifier for the user's device and either

  1. provide a function the SDK can call to send a custom push notification via the sendPushNotification prop

or

  1. upload your push notification credentials to Unum ID so we can send push notifications to your mobile app.
tip

Contact us for details on how to upload your push notification credentials.

SMS

Sends the user an SMS containing the deep link, which they open on their mobile device. Tapping the link in the message will open the corresponding app on the user's device and prompt them to share the requested credentials.

In order to use this fallback, you will need to provide the userInfo prop containing the user's mobile phone number.

You may send custom SMS messages by including the sendSms prop.

Email

Sends the user an email containing the deep link, which they open on their mobile device. Tapping the link in the email will open the corresponding app on the user's device and prompt them to share the requested credentials.

In order to use this fallback, you will need to provide the userInfo prop containing the user's email address.

You may send custom emails by including the sendEmail prop.

Trying the Next Fallback

If for some reason the first fallback option offered to a user doesn't work for them (maybe they turned off push notifications or any number of other things), the SDK will offer the next available option.

tip

Using all fallbacks allows you to handle the vast majority of edge cases:

  • Broken phone camera / doesn't know how to scan:
    QR code → push notification
  • Didn't accept / disabled push notifications:
    push notification → SMS
  • No cell service:
    SMS → email

API

The SDK exports a single UnumIDWidget component, which encapsulates all of its functionality. You configure it by setting its props.

Props

env

  • string
  • required
  • either sandbox or production
  • Determines which Unum ID SaaS environment the React Web SDK will connect to.

apiKey

  • string
  • required
  • Your Web SDK API key (obtained from Unum ID).
danger

Web SDK API keys are environment specific (see above). Make sure you are using the correct key!

userInfo

  • UserInfo
  • optional
  • Information about the user (push notification identifier(s), phone number, and/or email).
    • pushToken (optional): An object containing a push notification identifier from the user's device as well as your push notification provider, or an array of these objects.
      • value (required): the push notification token from the user's device.
      • provider (optional): The push notification provider. Supported values are 'APNS' (Apple Push Notification Service) and 'FCM' (Firebase Cloud Messaging). This is optional but highly recommended. If it is not included, we will attempt to determine the provider based on the token value and your uploaded push notification credentials.
    • phone (optional): The user's mobile phone number. Including this enables us to send deep links via SMS.
    • email (optional): The user's email address. Including this enables us to send deep links via email.

presentationRequest

  • PresentationRequestPostDto
  • optional
  • Created on your server with the Server SDK.
  • You may provide this prop in combination with setting createInitialPresentationRequest (below) to false for more control over when the widget should display a PresentationRequest to the user.

createInitialPresentationRequest

  • boolean
  • optional
  • Whether the widget should immediately call createPresentationRequest on load.
  • You can combine this with the presentationRequest prop to gain control over when the initial PresentationRequest is created. By default, it is false if you provide the presentationRequest prop and true if you do not.

createPresentationRequest

  • () => Promise<PresentationRequestPostDto> | void
  • A function that should call your Server SDK to create a PresentationRequest.
  • If it resolves to a value, it's assumed that the value is a PresentationRequestPostDto object. If it doesn't return a value, you must provide the response via the presentationRequest prop in order for the widget to display the PresentationRequest. (As in a Redux application, where createPresentationRequest will probably be an async action creator of some sort.)
  • The SDK calls this function on an interval in order to ensure that it never displays an expired PresentationRequest.

sendPushNotification

  • (options: PushNotificationOptions) => Promise<SuccessResponse>
  • optional
  • A function that takes a PushNotificationOptions object and calls your backend to send a deep link via push notification.
  • If this prop is not provided, the push notification fallback option will send the Unum ID SaaS's default push notification.
  • If provided, this function will be used instead of the default push notification fallback.
note

You will have to upload your Apple and/or Firebase push notification credentials to our SaaS in order to use the default push notification implementation.

sendSms

  • (options: SmsOptions) => Promise<SuccessResponse>
  • optional
  • A function that takes an SmsOptions object and calls your backend to send a deeplink via SMS.
  • You may use the sendSMS function from the Server SDK to send the SMS or your own SMS provider.
  • If this prop is not provided, the SMS fallback option will send the Unum ID SaaS's default SMS message.
  • If provided, this function will be used instead of the default SMS fallback.

sendEmail

  • (options: EmailOptions) => Promise<SuccessResponse>
  • optional
  • A function that takes an EmailOptions object and calls your backend to send a deeplink via email.
  • You may use the sendEmail function from the Server SDK to send the email or use your own email provider.
  • If this prop is not provided, the email fallback option will send the Unum ID SaaS's default email message.
  • If provided, this function will be used instead of the default email fallback.

goToLogin

  • () => void
  • optional
  • A function that redirects the user to your existing login page.
  • You should provide this if you are using Unum ID as an additional authentication factor on top of your existing login.
  • If this prop is not provided, the login fallback option will not be available.

userCode

  • string
  • optional
  • A code that is associated with a unique user in your system. It should be short-lived (i.e. not a primary key in your database).
  • Allows the Holder App to call back to your system and reference a specific user
  • Example uses include associating a user in your system with the DID identifying them in Unum ID and just-in-time credential issuance.

Examples

No Fallbacks

The simplest possible use case. It allows the SDK to handle all PresentationRequest creation, and does not provide any additional fallback options.

import UnumIDWidget from '@unumid/web-sdk-react';

const App = () => {
const createPresentationRequest = async () => {
// Call your your Server SDK to create a PresentationRequest and return the response.
};

return (
<UnumIDWidget
env='sandbox'
apiKey='my_sandbox_api_key'
createPresentationRequest={createPresentationRequest}
/>
);
};

Fallbacks

A slightly more complex use case which allows the SDK to handle PresentationRequest creation, but enables fallback options by providing user info

import UnumIDWidget from '@unumid/web-sdk-react';

const App = () => {
return (
<UnumIDWidget
env='sandbox'
apiKey='my_sandbox_api_key'
userInfo={{
pushToken: {
provider: 'FCM', // push notification provider to use. 'FCM' = Firebase Cloud Messaging, 'APNS' = Apple Push Notification Service
value: 'eWxqQQDXRWCcKTA9Uey6SZ:APA91bHlrRXETfqqi-LXESlPGN3hVq1qP54hfvzZoMosE3Rw5tQ1D4fuLJIqPiMv50NUYB5Rn_dPPMI709UeZjGGq7Uv2u1QWHytu7FXfQvUyDOwyLtQhWLEs-XxFMMYMOwgWgiItiqF' // token obtained from your app on the user's device
}
email: 'mrplow@gmail.com', // The user's email is required to enable the email fallback.
phone: 'KL5-5555' // The user's phone number is required to enable the SMS fallback.
}}
createPresentationRequest={createPresentationRequest}
/>
);
};

User Bootstrapping and/or Just-In-Time Credential Issuance

Allows the Holder App to call back to your system with the user's DID, enabling functionality like user bootstrapping and just-in-time credential issuance (see also: verifySubjectCredentialRequests)

import UnumIDWidget from '@unumid/web-sdk-react';

const App = () => {
return (
<UnumIDWidget
env='sandbox'
apiKey='my_sandbox_api_key'
userInfo={{
pushToken: {
provider: 'FCM', // push notification provider to use. 'FCM' = Firebase Cloud Messaging, 'APNS' = Apple Push Notification Service
value: 'eWxqQQDXRWCcKTA9Uey6SZ:APA91bHlrRXETfqqi-LXESlPGN3hVq1qP54hfvzZoMosE3Rw5tQ1D4fuLJIqPiMv50NUYB5Rn_dPPMI709UeZjGGq7Uv2u1QWHytu7FXfQvUyDOwyLtQhWLEs-XxFMMYMOwgWgiItiqF' // token obtained from your app on the user's device
}
email: 'mrplow@gmail.com', // The user's email is required to enable the email fallback.
phone: 'KL5-5555' // The user's phone number is required to enable the SMS fallback.
}}
createPresentationRequest={createPresentationRequest}
userCode='my-user-code' // uniquely identifies the user in your system
/>
);
};

Controlled Request Creation

Gives your application more control over when the initial PresentationRequest is created. Enables custom push notification, SMS, and email fallbacks.

import { useState } from 'react';
import UnumIDWidget from '@unumid/web-sdk-react';

const App = () => {
// Save the PresentationRequest in local component state.
const [presentationRequest, setPresentationRequest] = useState();

const createPresentationRequest = async () => {
const options = {
// Customizable PresentationRequest options.
credentialRequests: [{
type: 'LoginCredential',
issuers: ['did:unum:5235d82e-5aac-4df4-adf2-7c6cc0cbec95']
}],
verifier: 'did:unum:a74fce7c-7dfa-4702-b85f-f68a854c3cfe'
};
// Call your Server SDK to create a PresentationRequest and save in the component state.
const response = await callBackend(options);
setPresentationRequest(response);
};

const sendEmail = async (options) => {
// Call your Server SDK to send a deep link via email and return the response.
};

const sendSms = async (options) => {
// Call your Server SDK to send a deep link via SMS and return the response.
};

const goToLogin = () => {
// Navigate to your login page.
};

return (
<UnumIDWidget
env='sandbox'
apiKey='my_sandbox_api_key'
userInfo={{
pushToken: {
provider: 'FCM', // push notification provider to use. 'FCM' = Firebase Cloud Messaging, 'APNS' = Apple Push Notification Service
value: 'eWxqQQDXRWCcKTA9Uey6SZ:APA91bHlrRXETfqqi-LXESlPGN3hVq1qP54hfvzZoMosE3Rw5tQ1D4fuLJIqPiMv50NUYB5Rn_dPPMI709UeZjGGq7Uv2u1QWHytu7FXfQvUyDOwyLtQhWLEs-XxFMMYMOwgWgiItiqF' // token obtained from your app on the user's device
}
email: 'mrplow@gmail.com', // The user's email is required to enable the email fallback.
phone: 'KL5-5555' // The user's phone number is required to enable the SMS fallback.
}}
presentationRequest={presentationRequest} // Provide the SDK with an already created PresentationRequest.
createInitialPresentationRequest={false} // Prevent the SDK from immediately creating a new PresentationRequest on load.
createPresentationRequest={createPresentationRequest} // We still need to provide the SDK with a createPresentationRequest function so that it can create a new PresentationRequest before the current one expires.
sendEmail={sendEmail}
sendSms={sendSms}
goToLogin={goToLogin}
userCode='my-user-code' // uniquely identifies the user in your system
/>
);
};

Redux

Applications using Redux and other similar state management libraries have some unique challenges. Side effects like creating resources usually happen in action creator functions, which dispatch actions to the store rather than returning values.

In this example, we're providing the SDK with our createPresentationRequest action creator to call, then selecting the created PresentationRequest from the store to provide separately.

import { useSelector } from 'react-redux';
import UnumIDWidget from '@unumid/web-sdk-react';

// Import your action creators. They have been wrapped in React hooks in this example, but your application may be different.
import { useActionCreators } from './hooks/actionCreators';

const App = () => {
// These functions can be defined as async action creators using redux-thunk, redux-saga, or other libraries.
const { createPresentationRequest } = useActionCreators();

// Select a previously created PresentationRequest from state.
const presentationRequest = useSelector(state => state.presentationRequest);

// Select the logged in user from state.
const loggedInUser = useSelector(state => state.loggedInUser);

const goToLogin = () => {
// Navigate to your login page.
};

return (
<UnumIDWidget
env='sandbox'
apiKey='my_sandbox_api_key'
userInfo={{
pushToken: {
provider: 'FCM', // push notification provider to use. 'FCM' = Firebase Cloud Messaging, 'APNS' = Apple Push Notification Service
value: 'eWxqQQDXRWCcKTA9Uey6SZ:APA91bHlrRXETfqqi-LXESlPGN3hVq1qP54hfvzZoMosE3Rw5tQ1D4fuLJIqPiMv50NUYB5Rn_dPPMI709UeZjGGq7Uv2u1QWHytu7FXfQvUyDOwyLtQhWLEs-XxFMMYMOwgWgiItiqF' // token obtained from your app on the user's device
}
email: 'mrplow@gmail.com', // The user's email is required to enable the email fallback.
phone: 'KL5-5555' // The user's phone number is required to enable the SMS fallback.
}}
presentationRequest={presentationRequest} // Provide the SDK with an already-created PresentationRequest.
createInitialPresentationRequest={true} // The SDK should immediately create a PresentationRequest on load.
createPresentationRequest={createPresentationRequest} // We still need to provide the SDK with a createPresentationRequest function so that it can create a new PresentationRequest before the current one expires.
goToLogin={goToLogin}
/>
);
};