Custom Form Fields

Step 1: Overview

Sometimes it is helpful to collect additional pieces of information when consumers fill out the verification form. SheerID provides metadata values for this purpose, which are key/value pairs that you can pass alongside the verification request. These metadata values are available to you later in Verification Reports.

Using Custom Form Fields, you can expose a form field to consumers and the value they enter will be saved as metadata.

Step 2: Install via the CDN

There are two methods of installing the SDK via CDN:

• Modal Form
• Embedded Form

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

Set Options

After step 2 you should have something like this:

<div id="my-form"></div>
<script type="module">
  import sheerId from "https://cdn.jsdelivr.net/npm/@sheerid/jslib@2/sheerid-install.js"

  // Create a program at my.sheerid.com
  var myProgramUrl = "<YOUR_PROGRAM_URL>"
  var myDiv = document.getElementById("my-form")
  var myForm = sheerId.loadInlineIframe(myDiv, myProgramUrl)
  myForm.setOptions({ logLevel: "info" })
</script

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

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.

myForm.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:

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

Other types of Custom Form Fields

You can create custom fields of type checkbox:

    {
        fieldId: "customCheckboxExample",
        fieldType: "checkbox",
        validate: (value) => {
            if (!value) {
               return "customCheckboxExampleRequired"; // this becomes `errorId.customCheckboxExampleRequired` in your localized messages object
            }
        }
    },

Note the following options are unused for checkboxes: placeholder, showPlaceholderAndHideLabel and required.

If you want to ensure that the checkbox is checked prior to form submission, use the validate callback. This allows you to create a specific error message like "customCheckboxExampleRequired", shown above. Just like text type custom fields, make sure to supply localized messaging:

myForm.setOptions({
  messagesWithLocale: {
    "en-US": {
      customCheckboxExampleLabel: "I agree to terms...",
      "errorId.customCheckboxExampleRequired":
        "You must agree to terms before proceeding",
    },
    es: {
      customCheckboxExampleLabel: "Estoy de acuerdo con los términos...",
      "errorId.customCheckboxExampleRequired":
        "Debe aceptar los términos antes de continuar",
    },
  },
})

Prefill Data in Custom Form Fields

You can prefill data in a custom form field just like a built-in field, just note that the data for custom fields exists in the viewModel’s metadata object:

For type text:

myForm.setViewModel({
  metadata: {
    favoriteHairColor: "pink",
  },
})

For type checkbox:

myForm.setViewModel({
  metadata: {
    customCheckboxExample: true,
  },
})