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

An overview of SheerID Installation Methods can be found here

This readme demonstrates options when SheerID is installed 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

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.

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

Custom form fields of type checkbox are available as well. They do not use placeholder or required values. You can construct a validation callback to enforce that they are true or false, and display any error message accordingly.

Hooks are a convenient way to run your own javascript function(s) when the core jslib does certain things. They are helpful because you don't need to know a lot about the system to do certain things at certain times.

To add a hook, call addHook with the HookName and a callback. The callback will be passed relevant parameter(s) that you may or may not choose to utilize.

sheerId.addHook({
  name: "ON_VERIFICATION_SUCCESS",
  callback: function (verificationResponse) {
    window.location = "new.html";
  },
});

At the time of writing, there are 4 hooks you can use:

ON_VERIFICATION_READY

When the page loads, several api requests take place. Once they've all returned, and the library has initialized, ON_VERIFICATION_READY is called. After calling this hook once, your callbacks are removed/reset to ensure this happens only once per page-load (UX-346)

Your callback is given the VerificationResponse object

ON_VERIFICATION_SUCCESS

Called right after the API responds with the success step, but before the viewModel is updated in response to that API response.

Your callback is given the VerificationResponse object

ON_VERIFICATION_STEP_CHANGE

Called any time the current viewModel's step is different from the API response (just received)'s step. In other words, when the library determines we're about to display a different step. Your callback is given the VerificationResponse object

ON_FORM_LOCALE_CHANGE

Called any time the current viewModel'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

See it in action here

In addition to overriding any message, you can add extra text to a specific region on the form. Normally no text is shown in these spots. To add text, just define it using setOptions() along with the appropriate message key:

sheerId.setOptions({
    messagesWithLocale: {
        "en-US": {
          extraMessageCollectAboveSubmit: 'Lorem ipsum...',
        },
        es: {
          extraMessageCollectAboveSubmit: 'Lorem ipsum... (es)',
        },
    },
});

At this time only extraMessageCollectAboveSubmit is available. This message with show right above the Submit button on the collect step for any Segment.