JavaScript Library

The SheerID JavaScript library is at once a client for the SheerID REST API, an engine for rendering verification forms on your site, and a data collection tool for your verification programs.

Overview

This guide introduces advanced topics for using the SheerID JavaScript library, including UI customization, available JSAPI methods, and form restructuring options.

In order to proceed, you must have already created an account and a new verification at MySheerID. If you have not done so, please see the Account Setup page in our Getting Started documentation.

Installation

Retrieve your programId from your Program tab in MySheerID.

Then install the JS library using a script tag, calling the library from our CDN.

Add the following to the <head> of your html file.

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@sheerid/jslib@2/sheerid-install.css"
  type="text/css"
  crossorigin="anonymous"
/>

Render the verification form in a div.

<div id="my-form"></div>
<script type="module">
  import sheerId from "https://cdn.jsdelivr.net/npm/@sheerid/jslib@2/sheerid-install.js"

  // Create a program at my.sheerid.com
  var myProgramUrl = "<YOUR_PROGRAM_URL>"
  var myDiv = document.getElementById("my-form")
  var myForm = sheerId.loadInlineIframe(myDiv, myProgramUrl)
  myForm.setOptions({ logLevel: "info" })
</script>

You should now see a rendered form on your site. To test the form’s functionality, see the Test Program page in our knowledge base.

Customization

You have full control over the appearance of the verification forms on your site, from an out-of-the=box implementation using a form rendered by our JavaScript library, to a completely custom form that bypasses our JavaScript library and interacts with SheerID directly through our REST API.

This guide assumes that you would like to use our JavaScript library in part to perform at least one of the following functions:

Render a verification form and/or individual fields on your site.
Collect user-submitted data for reporting and marketing purposes.
Interact with the SheerID service as an API client, handling requests and responses to move verifications along efficiently.

If so, great! We’ll get into some of the available customization options below.

If you are planning to render your own forms and collect your own user data, and only need to communicate with our REST API, see REST API.

Direct (Mock) Step Access

When rendering the entire form, you can directly access any step in the flow with a query parameter. This makes it easy to refresh the page and see your CSS changes without having to fill out the form repeatedly.

We recommend styling each of these steps to suit your brand, since it’s likely that many users will reach all of them.

Note: Mock steps are not connected to our servers and will not work if you submit data. To test the flow, see Test Program.

The following table shows the available UI for different steps or states a user may find themself in during a student verification flow. The right column gives the query parameter you use to access the UI for your program, and links to an example.

Verfication Step/State	Query Parameter
Collect Personal Info	?mockStep=collect
Pending State (static timer)	?mockStep=pending
Success	?mockStep=success
Doc Upload	?mockStep=docUpload
Doc Upload Pending State	?mockStep=pending&mockPreviousStep=docUpload
Doc Upload Pending & Alerting State	?mockStep=pending&mockPreviousStep=docUpload&alerting=true
Doc Review Limit Exceeded	?mockStep=docReviewLimitExceeded
Loading¹	?mockStep=loading
SSO	?mockStep=sso
SSO Pending State	?mockStep=pending&mockPreviousStep=sso
Include custom reward code	?mockStep=success&mockRewardCode=foobar
Include custom redirect URL (and present redirect button)	?mockStep=success&mockRedirectUrl=https://google.com
Errors	?mockStep=error
Errors: Check for a specific scenario	?mockStep=error&mockErrorId={errorId} where `{errorId}` is one of the error IDs listed in our REST API reference.
SMS loop	?mockStep=smsLoop
Email loop	?mockStep=emailLoop
Cancel email loop	?mockStep=cancelEmailLoop

¹ This is a special case where we show the loading spinner so it can be styled. Program information is not available for this application state.

Internationalization (i18n)

We offer language for your verification form in a layered approach. The layers are:

SheerID default messages
Per-program (overrides “default”)
JavaScript Library (overrides “per-program” and “default”)

SheerID Default Messages

All of the words and phrases shown in our verification flows are offered in a variety of languages. You can see which messages are available in the REST API reference.

Per-Program Overrides

Certain phrases can be customized by editing your program at MySheerID, using the Customize Experience step.

JavaScript Library Overrides

You may specify messages when initializing your form using the setOptions method in Javscript.

<script>
    myForm.setOptions({
        messages: {
            'step.personalInfo.title': 'Verify (js options override)',
        },
    });
</script>

Note that all messages objects are flattened, so you can use a dot-string property or full objects:

<script>
    myForm.setOptions({
        messages: {
            // dot-string works
            'step.personalInfo.title': 'Verify (js options override)',

            // object works too!
            step: {
                personalInfo: {
                    subtitle: 'Verify Subtitle (js)',
                },
            },
        },
    });
</script>

See a live example here.

JSAPI Methods

The SheerID form objects provide the following methods to assist you with customizations.

setOptions()
setViewModel()
on() & once()

setOptions()

Accepts the following keys: logLevel, mockStep, locale, messages, urlFaq

Example:

myForm.setOptions({
    logLevel: 'info',
});

setViewModel()

Parts of the form can be prefilled with setViewModel.

myForm.setViewModel({
    firstName: 'Jane',
    lastName: 'Doe',
});

setting metadata

Metadata to be submitted alongside the form data can be set on the viewModel. Accepts up to 20 custom key/value pairs and will pass data through with verification request. Each key and value has a max length of 256 characters. Any metadata keys/values added here will be included in our verification reports.

Example:

myForm.setViewModel({
    metadata: {
        key1Name: 'value1',
        key2Name: 'value2',
    },
});

Using our pre-defined metadata key optin will render an opt-in checkbox on your program. Example:

myForm.setViewModel({
    metadata: {
        optin: '',
    },
});

Event hooks

The form objects returned from modals or from inline iframes have some methods to run your own code when events happen inside the verification process.

Note: Event hooks require v2+ of sheerid-install.js

.on(hook: HookEventName, callback: (data) => void): UnsubscribeFunction
// Will call your callback anytime the named event occurs.
// Returns a function to remove this listener

.once(hook: HookEventName, callback: (data) => void): UnsubscribeFunction
// Will call your callback the next time the named event occurs.
// Returns a function to remove this listener

Examples

myForm.on('ON_VERIFICATION_SUCCESS', (verificationResponse) => {
    // Run your code here
});

myForm.once('ON_VERIFICATION_SUCCESS', (verificationResponse) => {
    // Run your code here exactly once.
});

Hook listeners return an unsubscribe function you can use to remove listeners.

var unsubscribe = myForm.on('ON_FORM_LOCALE_CHANGE', (locale) => {
    window.alert(`new locale: ${locale}`);
});

unsubscribe();
// The above callback will no longer run on locale changes.

Hook events

There are 4 hooks you can use. See the API documentation about VerificationResponse details.

ON_VERIFICATION_READY

Triggered when the form is ready to receive user input.

Your callback is given the VerificationResponse object
ON_VERIFICATION_SUCCESS

Triggered when the form receives a success response from the api.

Your callback is given the VerificationResponse object
ON_VERIFICATION_STEP_CHANGE

Called any time the currentStep changes in the VerificationResponse

Your callback is given the VerificationResponse object
ON_FORM_LOCALE_CHANGE

Called any time the current form’s locale is updated. Typically, this action occurs whenever a user changes their locale using the locale picker.

Your callback is provided the Locale string