This is a lightweight React library that allows a web client to display and sends
Please contact us for frameworks other than React.
- React v16.8.0 and above
- English language (internationalization coming soon)
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.
This is available at Git and can be cloned using:
The Web SDK is currently only available via GitHub, but will be available via the NPM and Yarn registries soon.
Alternatively, you can add the following to your
package.json and run
npm install or
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.
An Unum ID
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 Web SDK determines how it displays them based on the browser's userAgent.
- 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.
In some situations, neither a QR code nor a button is convenient, so the SDK uses fallback options in this order:
- Push Notification: sends a push notification to the user's device.
- SMS: sends the user an SMS message containing the deep link, which they open on their mobile device.
- Email: sends the user an email containing the deep link, which they open on their mobile device.
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.
The SDK exports a single
WidgetHostAndController component, which encapsulates all of the SDK's functionality.
- The name of your Unum ID powered mobile app.
- Information about the user (push notification identifier, phone number, and/or email).
- The SDK will use this to determine which fallback options are available.
- Created on your server with the Server SDK.
- You may provide this prop in combination with setting
falsefor more control over when the widget should display a
PresentationRequestto the user.
- Path to the image to display as a deep link button.
- Whether the widget should immediately call
- You can combine this with the
presentationRequestprop to gain control over when the initial
PresentationRequestis created. By default, it is
falseif you provide the
trueif you do not.
() => Promise<PresentationRequestResponse> | void
- A function that should call your Server SDK to create a
- 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
presentationRequestprop in order for the widget to display the
PresentationRequest. (As in a Redux application, where
createPresentationRequestwill 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
(options: EmailOptions) => Promise<SuccessResponse>
- A function that takes an
EmailOptionsobject and calls your backend to send a deeplink via email.
- You may use the
sendEmailfunction 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.
(options: SmsOptions) => Promise<SuccessResponse>
- A function that takes an
SmsOptionsobject and calls your backend to send a deeplink via SMS.
- You may use the
sendSMSfunction 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.
() => void
- 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.
The simplest possible use case. It allows the SDK to handle all
PresentationRequest creation, and does not provide any additional fallback options.
A slightly more complex use case which allows the SDK to handle PresentationRequest creation, but enables fallback options.
Gives your application more control over when the initial PresentationRequest is created. Enables fallback options.
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.