BriteForms Setup Guide

Basic Install


 

1. Add Trusted Domains


In order for BriteForms to work in production environments, you need to specify which domains are authorized to run BriteVerify scripts. This is done at the account level, so that you only have to authorize a domain once and it will work for all your forms.

To add a trusted domain, go to Forms and click on Trusted Domains. From there enter the url of the domain you want to authorize. For example, if you wished to authorize app.mysite.com, you would enter https://app.mysite.com. Please note that you will need to authorize the exact domain as we do not support wildcards at this time. For example, if you want the script to run on both mysite.com and www.mysite.com you will have to add both of those domains.

 

2. Create a Form


Next you need to create your first BriteForm.

  1. Click on the "Forms" tab.
  2. Click "Install Form."
  3. Enter a name for the new form.
  4. Click "Create Form."
 

3. Install Client-Side JavaScript


  1. You should now be viewing the Form Settings for your new form.
  2. Paste the JavaScript code snippet generated for you from the form settings into your webpage just before the close of the </body> tag. The snippet includes your public BriteForm key, which does not need to be hidden.

The snippet should look like this:

<!-- Put this just before the closing body tag -->
<script type='text/javascript'>
  window.briteFormSettings = { formKey: 'your-public-briteform-key' };
</script>
<script src='//cdn.briteverify.com/bforms.js' type='text/javascript'>
</script>

This will work on the first form on the page provided that the form contains an <input>field with a type equal to email.

 

4. Testing Your Form


Important note: By default your form is set to test mode. You will ONLY be able to test the following addresses:

This will allow you to develop and run BriteForms from your local machine without having to authorize any domains or worry about triggering BriteVerify's fraud tools and security countermeasures. In test mode you will need to use certain emails to simulate certain events. Submissions and Verifications will still be tracked but they will all be marked as test transactions and only appear in reporting when the form is in test mode.

For the "suspected fraudulent" test transactions using fraud@briteforms.com, the PIN you can type in to 'pass' the confirmation dialog will always be 5555.

 

5. Setup Server-Side Certification (optional)


For many users, client-side verification is enough. But client-side verification can still be bypassed by a determined attacker. If you want to ensure that fraud is not occurring on your forms you need to install the second line of defense confirming each form submission using our Token Certification API on the server side.

Each BriteForm that is submitted to your server includes a hidden field calledbriteform_token. You can pass this token plus the email submitted with the form to our REST API endpoint in order to ensure the submission is indeed valid and originated from an actual browser session. You must authenticate the request by passing along yourprivate key. You should keep your private key secret; contact support if you think it may have been compromised. Your private key is listed in the text above the code snippet in the BriteForms screen.

 

Ruby Example


def create
  rjson = RestClient.get('https://certify.briteverify.com/api/submissions/certify.json',
    {
      params: {
        apikey: 'your-private-api-key'
        form_key: 'your-public-briteform-key',
        briteform_token: params[:briteform_token],
        email: params[:user][:email]
      }
    }
  )
  result = JSON.parse(rjson).symbolize_keys!

  if result[:fraud]
    flash.now[:alert] = "You don't appear to be human. You may not proceed."
    # ...
  else
    # finish normally
  end
end
 

PHP Example


$req_url="https://certify.briteverify.com/api/submissions/certify.json?apikey=$your_private_key&form_key=$your_public_briteform_key&briteform_token=".urlencode($_REQUEST['briteform_token'])."&email=".urlencode($_REQUEST['email']);
$res=file_get_contents($req_url);
$ans=json_decode($res);
if($ans->fraud) {
  print "Fraud detected!";
} else {
  print "Proceed normally...";
}
 

6. Turn Form Live


When you are ready to promote your form to production click on your form and move the slider from "Test" to "Live."

The test email addresses from Test Mode will no longer validate as before (they are for test mode only). Confirmation Dialogs and associated confirmation emails will only be prompted by transactions that BriteVerify deems 'suspicious.' Otherwise, valid emails will be permitted through the form, and invalid emails will be blocked from submitting the form.

The contents of BriteForms confirmation emails are fixed and cannot be customized at this time.

 

Alternate Setup Options


If BriteForms isn't automatically activating on your page or it isn't activating on the correct field, then you can use one of these alternative methods below. Either one will work, use whichever you prefer. These methods will allow you to manually specify which form and which field should be verified by BriteForms.

 

Data Attributes


Alternatively, you may specify your public BriteForm key and the email field inline within the form using data-* attributes.

This can be useful if we can't find your email field automatically, or if the form you want to verify isn't the first one on the page.

<form data-briteform-key='your-public-briteform-key'>
  <input type='text' data-britefield='email'></input>
  <input type='submit'></input>
</form>
<script type="text/javascript" src="//cdn.briteverify.com/bforms.js" >
</script>
 

Via JavaScript


Additionally, you may specify the public BriteForm key and the email field using Javascript. This can be useful if you aren't allowed to modify the attributes of the form on your page, but can insert additional JavaScript.

<script type="text/javascript">
  window.briteFormSettings = {
    formKey: 'your-public-briteform-key',
    form: document.getElementById("my_form_id"),
    emailInput: document.getElementById("my_emailfield_id")
  };
</script>
<script type="text/javascript" src="//cdn.briteverify.com/bforms.js" >
</script>
 

Custom API


We allow you to add new functionality and customize nearly every aspect of the BriteForms experience via our api.

 

Verification Events


You can hook into BriteForm verification events to add additional functionality.

 

Events


  • verification:start
  • verification:end

Each event passes a verification object into the callback function.

{
  el: input#email
  address: "james@yahoo.com",
  account: "james",
  domain: "yahoo.com",
  status: "invalid",
  error_code: "email_account_invalid",
  error: "Email account invalid",
  disposable: false,
  role_address: false
}

The el object will be the email field to which the verification is attached.

 

Example Event API Usage


In this example we show how to force confirmation on role and disposable emails using the event api. You will instantiate the script. You will not use window.briteFormSettings, but instead create an instance of the BriteForm class yourself directly.

<!-- Put this just before the closing body tag -->
<script src='//cdn.briteverify.com/bforms.js' type='text/javascript'></script>
<script type='text/javascript'>
window.briteForm = BriteForm.create({
  formKey: 'your-briteform-key',
  emailInput: document.getElementById("my_emailfield_id")
});

briteForm.on('verification:start', function(verification){
  $(verification.el).addClass('verifying');
});

briteForm.on('verification:end', function(verification){
  $(verification.el).removeClass('verifying');
  if(verification.disposable || verification.role_address){
    window.alert("Please don't input disposable or role addresses!");
    //You will have to also prevent the form submission here
  }
});
<script>
 

Running Script in Manual Mode


You can run BriteForms in manual mode which will turn off the automatic verification widget on the email field and allow you to customize your own look and feel, while still maintaining all the advantages of BriteForms. To do so you simply specify manual mode and then hook into the verification:start and verification:end events to code your own behavior.

<script type="text/javascript" src="//cdn.briteverify.com/bforms.js" >
</script>
<script>
window.briteForm = BriteForm.create({
  formKey: 'your-briteform-key',
  form: document.getElementById("my_form_id"),
  emailInput: document.getElementById("my_emailfield_id"),
  manual: true
});

briteForm.on('verification:start', function(verification){
  $(verification.el).addClass('verifying');
});

briteForm.on('verification:end', function(verification){
  $(verification.el).removeClass('verifying');
  if(verification.status === 'invalid'){
    alert('Email is invalid. Please Correct');
  }
});
</script>
 

.NET Form Validation


Since ASP.NET forms behave a little different than standard Web Forms, we have provided some utility methods to help with managing the verification lifecycle.

The BriteForm API exposes a validate method that can be used for client side validation. Since ASP.NET forms may not actually fire a submit event on the form, it might be best to use the validate method and attach it to the click event of the button control that submits the form to the server.

 

<script type="text/javascript">
  window.briteForm = BriteForm.create({
    formKey: 'your-briteform-key',
    form: document.getElementById("my_form_id"),
    emailInput: document.getElementById("my_emailfield_id")
  });
</script>

<asp:Button ID="btnSave" runat="server" Text="Create" OnClientClick="return briteForm.validate();"/>
 

Removing the briteform_token hidden field


By default BriteForms adds a hidden field with the BriteForm token for server side certification of the form data. To prevent the hidden field from being added to the form automatically, pass the addToken: false option and the hidden field will not be added. You can obtain the briteForm token by making a call to the briteForm object to obtain it.

<script type="text/javascript">
  window.briteForm = BriteForm.create({
    formKey: 'your-briteform-key',
    form: document.getElementById("my_form_id"),
    emailInput: document.getElementById("my_emailfield_id")
  });
  var briteFormToken = briteForm.getToken();

  function sendDataViaAjax(){
    if(!briteForm.validate()){
      return false;
    }

    var formData = {
      name: document.getElementById("name_field").value(),
      email: document.getElementById("my_emailfield_id").value();
      token: briteFormToken
    }

    // submit data to the server.

  }
</script>