Advanced options for the phone verification widget

In this page

The phone verification widget can be customised to suit your needs. The integration instructions should allow you to set up quickly, and once this is done, you can tweak the behaviour.

There are three attributes that can be customised. These are: countryNotAllowed, nonMobile and unverified. For each of these, you are able to set a rule and a message. See the API docs for a definition for these attributes.

There are three rules you can pick from:

• allow will trigger the widget to show a green tick, and no error message.
• warn will trigger the widget to show an orange warning icon, and an error message.
• block will trigger the widget to show a red cross, and an error message. It will also prevent the user from submitting the form.

When using warn or block you can also provide a customised message.

Custom rules and messages

Below is an example of the rules that can be used to customise the widget:

    
rules: {
  unverified: {
    rule: "block",
    message: false
  },
  nonMobile: {
    rule: "warn",
    message: "We would prefer a mobile phone number."
  },
  countryNotAllowed: {
    rule: "allow"
  }
}
    
  

Note: Both the rules and messages are optional and configurable so can be customised to suit your needs.

Removing the rule will result in the default rule being applied.

Removing the message line will result in the default message being displayed when the rule is enforced.

Setting message: false will result in no message being displayed when the rule is enforced.

Default rules

In the absence of a specified rule, the following defaults are applied:

    
rules: {
  unverified: {
    rule: "block"
  },
  nonMobile: {
    rule: "allow"
  },
  countryNotAllowed: {
    rule: "block"
  }
}
    
  

Default messages

In the absence of a supplied message, the following default messages will be returned when the response matches the rules (supplied or default):

Custom styling

Our Javascript widget includes a stylesheet that defines the visual aspects of the icons and messages that are displayed. You may decide to adjust the colours or fonts used to more closely match the branding of the page in which the widget is embedded. This can be done easily by overriding the default styles that are included in the file.

You can inspect the styles here (tip: use an online beautifier to make it easier to read) and then define your own CSS rules to override the default styles.

View a code example, where we use the Phone Widget with a different colour for the message.

Here is an example of the html elements that are included in the DOM:

    
<span class="af-pv-icon-block af-pv-icon" style="top: 768.943px; left: 632.458px; height: 26.5px; width: 26.5px;"></span>
<span class="af-pv-message" aria-live="polite" style="left: 270px; top: 811.484px; width: 400px; display: inline-block;">It looks like there could be a problem with this phone number. You must enter a correct phone number</span>
    
  

Using a country select field

The widget can be configured to watch a country field and apply the selected country to the query. This significantly improves verification outcomes on forms being completed by people from more than one country.

View this code example demonstrating the use of the country select field.

Collection of phone number metadata using the widget events

The widget can be configured to collect metadata from the Phone Verification API response and populate this into fields of your form (hidden or visible to the user). The widget returns two events that can be used for this purpose. To view the full list of the metadata attributes available for collection, see the javascript docs.

View this code example demonstrating the use of the widget events.

Working inside a modal

Because modals are usually static in the context of the page, it is recommended when initialising the widget to provide a Node to the container option. This option takes an HTML Node that will be used as a basis for the HTML injected by the widget. As such, positioning of our loading indicator and feedback message to the user will still work as expected. An example of how to use the container option can be found here.