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.
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.
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 |
Loading1 | ?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 |
1 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: '',
}