Help

Getting Started with the Widget

NeverBounce’s Javascript widget is currently in beta! Access to the widget and widget settings are only available to those enrolled in our beta program. If you’d like to participate please send an email to support@neverbounce.com.

The NeverBounce JavaScript widget allows you to quickly and easily add our real-time verification services to your online forms.

Getting StartedAnchor

To get started, create a new JavaScript widget from the apps page here. You will be asked to give your application a name for easy identification within your dashboard. Additionally, you will want to specify any authorized domains or IP addresses from which the form can be used. More information about authorized domains can be found here. You may also want to specify throttling rules to prevent abuse. You can learn more about throttling here. Once you’re satisfied with your options, please click the ‘Save’ button. All these options can be changed and adjusted as needed after the application is created.

Installing the WidgetAnchor

Once you’ve created the app, you’ll be presented with your public API key and an HTML snippet. To install the widget simply copy the HTML snippet and place it just before the closing </body> tag on your website as seen below:

...

    <script type="text/javascript">
        _NBSettings = {
            apiKey: 'public_000000...'
        };
    </script>
    <script type="text/javascript" src="https://cdn.neverbounce.com/widget/dist/NeverBounce.js"></script>
</body>
</html>

Once you have the snippet on your site, you should notice any input elements using the email type are automatically detected by the widget. If your field doesn’t use the email type, you can add the data-nb attribute to force detection. Both of the fields below would be picked up by the widget:

<input type="email" name="email_field" />
<input type="text" name="email_field" data-nb />

Now that you have your fields setup, you should see the NeverBounce JavaScript widget working its magic when you start typing in these fields. By default disposables and invalids are prevented from submitting the form. If wish to change this, you can continue reading below in the Settings section.

Widget SettingsAnchor

There are two types of Settings for your widget: security settings and behavior settings. Security settings are controlled from your dashboard where you initially setup the widget. View your existing widgets here. Behavior settings are controlled from the HTML snippet placed on your site.

Security Settings

Authorized Domains

Authorized domains and IP addresses prevent your public API key from being used from unauthorized sources. Requests made with your public API key are only accepted when they come from one of your authorized sources.

If you do not specify any authorized domains or IP addresses, all requests made with your key will be processed regardless of location.

Throttling

Specifying throttling rules allow you to prevent users from abusing your forms. You can specify multiple rules to limit the number of verifications made in a given timeframe by IP or even globally across all IP addresses. When the limit is hit, the widget will treat the request as an unknown as not to block the transaction.

Not specifying throttling rules leave your widgets at risk for abuse. This may cause your credit balance to deplete or possible risk of account closure.

Behavior Settings

When you install the widget with the HTML snippet you may notice a line which reads _NBSettings. As you might suspect, this is where you specify the settings for the widget on your site. Initially, the snippet only includes the apiKey setting – this is the only setting needed to make the widget work. When more control is needed, the snippet below contains all the settings and their default values:

<script type="text/javascript">
_NBSettings = {

    /**
     * Message displayed in feedback div when email is acceptable
     * (See: feedback)
     */
    acceptedMessage: "Valid email",

    /**
     * The acceptable status codes. Other status codes will be rejected.
     * Default accepted codes are valid(0), catchall(3) and unknown(4)
     */
    acceptedStatusCodes: [0,3,4],

    /**
     * If this form doesn't use traditional form submission or you need to use
     * the 'submit' event on the form to do additional processing before
     * submission use this mode. This will disable traditional submission and let
     * you hook into two new events to handle form submission (nb:submit) and
     * rejection (nb:reject) based on the verification.
     */
    ajaxMode: false,

    /**
     * User's public api key; This is available from the apps page.
     */
    apiKey: undefined,

    /**
     * When enabled the default event listeners and handling is
     * disabled. Usage of this option will set the following
     * options to false:
     * - autoFieldHookup
     * - hiddenField
     * - feedback
     */
    apiOnly: false,

    /**
     * Hook API to fields tagged with `data-nb` or `email` type
     * This will create event listeners for these inputs and use our
     * internal handlers for creating the API requests and handing
     * the results.
     */
    autoFieldHookup: true,

    /**
     * When enabled the feedback displayed to the user (see: feedback)
     * will display the powered by NeverBounce logo.
     */
    displayPoweredBy: true,

    /**
     * When enabled we display a box indicating the status of the lookup.
     * This will be displayed on any field our FieldListener has attached
     * to.
     */
    feedback: true,

    /**
     * This is the class used on the feedback div. This class should use the
     * `display: none;` property in it's default state. The feedback handler
     * will set this to `display: block;` when necessary.
     * (see: feedback)
     */
    feedbackClass: "nb-feedback",

    /**
     * When enabled a hidden field will be added to the form containing
     * the result's text code.
     * This will only work for fields attached to the FieldListener.
     */
    hiddenField: true,

    /**
     * This is the time in milliseconds we allow between keystrokes before we
     * attempt to verify the input.
     */
    inputLatency: 600,

    /**
     * Message displayed in feedback div while waiting for an response
     * (see: feedback)
     */
    loadingMessage: "Loading...",

    /**
     * Message displayed in feedback div when email is rejected
     * (see: feedback)
     */
    rejectedMessage: "Invalid email",

    /**
     * Custom selector to use for the auto hookup. This can be any valid css
     * selector or several selectors comma separated.
     */
    selector: undefined,

    /**
     * Message displayed in feedback div when input doesn't pass the local regex check
     * (see: feedback)
     */
    softRejectMessage: "Enter an email",

    /**
     * Request timeout in milliseconds
     * After this threshold is reached the result is assumed unknown. This is likely
     * a trouble host that will take extra time to resolve.
     */
    timeout: 30000,

};
</script>
<script type="text/javascript" src="https://cdn.neverbounce.com/widget/dist/NeverBounce.js"></script>

For more advanced customization of the widget go here for details.