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 our Easy Install documentation to get started.

Installation

Retrieve your programId from your Program tab in MySheerID.

Program ID

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

  1. Add the following to the <head> of your html file.
     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@sheerid/jslib@latest/sheerid.css" type="text/css" crossorigin="anonymous" />
     <script src="https://cdn.jsdelivr.net/npm/@sheerid/jslib@latest/metrics.js" crossorigin="anonymous"></script>
    
  2. Add the SheerID JavaScript library in the <body>.
     <script src="https://cdn.jsdelivr.net/npm/@sheerid/jslib@latest/sheerid.js" crossorigin="anonymous"></script>
    
  3. 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 Verify a User and Document Upload instructions in the Easy Install section.

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 at least 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/jslib@latest/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 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 examples show how to mock the various steps on a student verification.

*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:

  1. SheerID default messages
  2. Per-program (overrides “default”)
  3. 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()

See our JavaScript Library Reference for details.

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: '',
}