Skip to main content

Web SDK

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

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.
+ More...
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.
+ More...
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 Web SDK and the Server SDK.

Reference Client Application#

This is available at Git and can be cloned using:

git clone https://github.com/UnumID/Verifier-Client-SDK-Client-Reference-App.git

Installation#

The Web SDK is currently only available via GitHub, but will be available via the NPM and Yarn registries soon.

npm install @unumid/web-sdk@https://github.com/UnumID/Verifier-Client-SDK.git

Alternatively, you can add the following to your package.json and run npm install or yarn install:

"@unumid/web-sdk": "https://github.com/UnumID/Verifier-Client-SDK.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.
+ More...
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.
+ More...
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.

Display Deep Links#

PresentationRequests are shared to an Unum ID-powered mobile app a user's device via deep links. The 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.

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: sends a push notification to the user's device.
  2. SMS: sends the user an SMS message containing the deep link, which they open on their mobile device.
  3. Email: sends the user an email containing the deep link, which they open on their mobile device.
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

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.We provide a goToLogin() function for this purpose.

API Props#

The SDK exports a single WidgetHostAndController component, which encapsulates all of the SDK's functionality.

applicationTitle#

  • string
  • required
  • The name of your Unum ID powered mobile app.

userInfo#

  • UserInfo
  • required
  • Information about the user (push notification identifier, phone number, and/or email).
  • The SDK will use this to determine which fallback options are available.

presentationRequest#

  • PresentationRequestResponse
  • 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.

deeplinkImgSrc#

  • string
  • optional
  • Path to the image to display as a deep link button.

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<PresentationRequestResponse> | void
  • optional
  • A function that should call your Server SDK to create a PresentationRequest.
  • If it returns a value, it's assumed that the value is a PresentationRequestResponse. 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.

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 your own email provider.
  • If this prop is not provided, the email fallback option will not be available.

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 not be available.

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.

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 WidgetHostAndController from '@unumid/web-sdk';
// Import an image to use for the (mobile) deep link button.
// In this example, images are stored in an 'assets' directory. Your application may be different.
import deeplinkImgSrc from '../assets/deeplink-button-image.png';
const App = () => {
const createPresentationRequest = async () => {
// Call your your Server SDK to create a PresentationRequest and return the response.
};
return (
<WidgetHostAndController
applicationTitle="My Application"
userInfo={{}}
createPresentationRequest={createPresentationRequest}
deeplinkImgSrc={deeplinkImgSrc}
/>
);
};

Fallbacks#

A slightly more complex use case which allows the SDK to handle PresentationRequest creation, but enables fallback options.

import WidgetHostAndController from '@unumid/web-sdk';
// Import an image to use for the (mobile) deep link button.
// In this example, images are stored in an 'assets' directory. Your application may be different.
import deeplinkImgSrc from '../assets/deeplink-button-image.png';
const App = () => {
const createPresentationRequest = async () => {
// Call your Server SDK to create a PresentationRequest and return the 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 (
<WidgetHostAndController
applicationTitle="My Application"
userInfo={{
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}
deeplinkImgSrc={deeplinkImgSrc}
sendEmail={sendEmail}
sendSms={sendSms}
goToLogin={goToLogin}
/>
);
};

Controlled Request Creation#

Gives your application more control over when the initial PresentationRequest is created. Enables fallback options.

import { useState } from 'react';
import WidgetHostAndController from '@unumid/web-sdk';
// Import an image to use for the (mobile) deep link button.
// In this example, images are stored in an 'assets' directory. Your application may be different.
import deeplinkImgSrc from '../assets/deeplink-button-image.png';
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 (
<WidgetHostAndController
applicationTitle="My Application"
userInfo={{
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.
deeplinkImgSrc={deeplinkImgSrc}
sendEmail={sendEmail}
sendSms={sendSms}
goToLogin={goToLogin}
/>
);
};

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 WidgetHostAndController from '@unumid/web-sdk';
// 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';
// Import an image to use for the (mobile) deep link button.
// In this example, images are stored in an 'assets' directory. Your application may be different.
import deeplinkImgSrc from '../assets/deeplink-button-image.png';
const App = () => {
// These functions can be defined as async action creators using redux-thunk, redux-saga, or other libraries.
const { createPresentationRequest, sendSms, sendEmail } = 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 (
<WidgetHostAndController
applicationTitle="My Application"
userInfo={{
email: loggedInUser.email, // The user's email is required to enable the email fallback.
phone: loggedInUser.mobilePhoneNumber // 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.
deeplinkImgSrc={deeplinkImgSrc}
sendEmail={sendEmail}
sendSms={sendSms}
goToLogin={goToLogin}
/>
);
};