SheerID JavaScript Library

See https://developer.sheerid.com for more

Step 1: Overview

An overview of SheerID Installation Methods can be found here

This readme demonstrates options when SheerID is installed via the CDN.

Step 2: Install via the CDN

Click here for instructions. Once you have an html page with a form rendered in a div, you are ready to reference the various options outlined in this README

Set Options

After step 2 you should have something like this:

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

Many of the custom behaviors SheerID offers are exposed via setOptions. sheerId.setOptions({logLevel: 'info'}); is setting the log level of the library to info, for increased debugging output while testing your program.

Available Options

Pass all or a part of the following object to sheerId.setOptions():

customFormFields: [],
doFetchTheme: true,
httpRequestTimeout: 10000, // ms
locale: null,
logLevel: "error",
messagesWithLocale: {},
minimumOrganizationSearchLength: 1,
mockStep: undefined,
mockSubSegment: undefined,
mockErrorId: undefined,
mockRewardCode: undefined,
mockRedirectUrl: undefined,
mockResponse: undefined,
privacyPolicyUrl: undefined,
useFingerprinting: false,
verificationId: undefined,

For a full list of options, see https://developer.sheerid.com/jslib-api-docs/index.html#options

Custom Form Fields

Custom form fields have the following interface:

export interface FormFieldConfig {
    fieldId: string; // should be camelCase. Will be used the key in metadata where the value is stored. Also used to build localization message keys
    fieldType: string; // Only text for now. Later: | "select" | "radio", etc
    validate: (value: string | boolean) => ErrorId | string | undefined; // If value is invalid, return an error id or string so the error msg can be localized and shown
    showPlaceholderAndHideLabel?: boolean;
    required?: boolean;
}

At the time of writing, only fieldType=text is supported. Provide an array of custom form fields to setOptions and they will be added below other form fields.

The data that is collected for custom fields is attached to the verification as metadata with the metadata key = fieldId. This data will show up in Verification Reports.

sheerId.setOptions({
    customFormFields: [
        {
            fieldId: "favoriteHairColor",
            fieldType: "text",
            showPlaceholderAndHideLabel: false,
            required: true,
            validate: (value) => {
                if (!value) {
                    return "hairColorRequired"; // this becomes `errorId.hairColorRequired` in your localized messages object
                }
            }
        },
    ],
});

You will want to provide localized messaging for your field, which can be done with setOptions as well:

sheerId.setOptions({
    messagesWithLocale: {
        "en-US": {
            favoriteHairColorPlaceholder: 'My hair is...',
            favoriteHairColorLabel: 'Hair Color',
            'errorId.hairColorRequired': 'Hair Color is Required',
        },
        es: {
            testPlaceholder: 'Mi pelo es...',
            testLabel: 'Color de pelo',
            'errorId.myCustomErrorId': 'Se requiere color de cabello',
        },
    },
});

Note: placeholder and label message keys are automatically formulated based on the fieldId: ${fieldId}Placeholder and ${fieldId}Label

See it in action: https://jsfiddle.net/AaronSheerID/n91p2sya/