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/[email protected]/sheerid.css" type="text/css" crossorigin="anonymous" />
 <script src="https://cdn.jsdelivr.net/npm/@sheerid/[email protected]/metrics.js" crossorigin="anonymous"></script>

Add the SheerID JavaScript library in the <body>.

 <script src="https://cdn.jsdelivr.net/npm/@sheerid/[email protected]/sheerid.js" crossorigin="anonymous"></script>

Render the verification form in a div.

 <div id="my-form"></div>
 <script>
     var sheerId = window.sheerId;
     sheerId.setOptions({logLevel: 'info'});

     // Create a program at my.sheerid.com
     var myProgramId = '<YOUR_PROGRAM_ID>';
     var myDiv = document.getElementById('my-form');
     var myForm = new sheerId.VerificationForm(myDiv, myProgramId);
 </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.

Note: SheerID uses Subresource Integrity to ensure that your target resources are securely downloaded over CDN.

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.

CSS

We encourage you to include SheerID’s stylesheet to provide basic style for the form.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@sheerid/[email protected]/sheerid.css" type="text/css" crossorigin="anonymous" />

Override CSS

You can override styles by including your own stylesheet after SheerID’s. View an example of overwritten styles on JSFiddle here.

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>
sheerId.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>
sheerId.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 JavaScript library provides the following JSAPI methods to assist you with customizations.

setOptions()
setMetadata()
getMetadata()

setOptions()

Accepts the following keys: restApi, logLevel, mockStep, locale, messages, urlStudentFaq, urlSeniorFaq, urlMilitaryFaq, and urlTeacherFaq

Example:

sheerId.setOptions({
    logLevel: 'info',
})

setMetadata()

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:

sheerId.setMetadata({
    key1Name: 'value1',
    key2Name: 'value2',
})

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

sheerId.setMetadata({
    optin: '',
})

getMetadata()

Returns an object containing all current metadata key/value pairs.

Example:

In:

sheerId.getMetadata()

Out:

{
   key1Name: 'value1',
   key2Name: 'value2',
   optin: '',
}