Advanced options

The phone verification JavaScript widget is highly customisable to suit your needs. The installation instructions should allow you to get started quickly. Once this is done, you can further tweak the widget's behaviour using the options below.

Attributes

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 responses

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

Response	Default warn message	Default block message
unverified	"Phone number not verified."	"Phone number not verified."
countryNotAllowed	"Preferred countries: {LIST}"	"Allowed countries: {LIST}"
nonMobile	"Mobile phone numbers preferred."	"Mobile phone numbers required."

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.

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.