Web Event Capture

This section provides comprehensive instructions on how to integrate your site with Metroleads via MetroLeads Website Integration or MWI. MWI allows to you to track the following:

And will allow to track in the next version:

Integration Guide

Visits & Click Tracking

Use the code below in your pages. It automatically injects a tracking Javascript from our servers that will send visit and click data to MetroLeads. To use this on your pages, copy the code snippet, replacing <company_id> and <website_id> with your own MetroLeads identifiers. Identifiers are UUIDs and are of the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx and are available from the Settings > Websites section of MetroLeads. For any further assistance please contact support team.

<script type="text/javascript">
  (function() {
    var mgElement = document.createElement('script');
    mgElement.type = 'text/javascript'; mgElement.async = true;
    mgElement.src = '//tcdn.metrowidget.com/quasar.min.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(mgElement, s);

    // Handle Script loading
    var done = false;
    var head = document.getElementsByTagName("head")[0] || document.documentElement;
    mgElement.onload = mgElement.onreadystatechange = function() {
      if ( !done && (!this.readyState ||
              this.readyState === "loaded" || this.readyState === "complete") ) {
          done = true;
          mg = new MG({}, '<company_id>', '<website_id>');
          mg.init();
      }
    };
  })();
</script>

Although the tracking code is asynchronous and will not hamper page load experience we highly recommend that you add it to the bottom of the page right before the tag.

Form Integration

Basic Integration

The tracking snippet will by default also capture forms without any modification to the forms in your HTML. However modifications are required if:

A simple form might look like this:

<form id="enquiry" action='submit.html'>
    First Name: <input type="text" id="first_name" />
    Last Name: <input type="text" id="last_name" />
    Email address: <input type="text" id="email" />
    Phone number: <input type="text" id="phone" />
    Sex: <input type="radio" name="sex" value="male"> Male
         <input type="radio" name="sex" value="female"> Female
    <input type="submit"/>
</form>

When it is submitted the following data is shown in the Form Manager of MetroLeads:

Form Without ML Fields

As clearly visible this is not usable and MetroLeads allows you to make simple modifications to the form (without Javascript code) to send meaningful labels that align with your business.

<form id="enquiry" action='submit.html' data-ml-form="Contact Us">
    First Name: <input type="text" id="first_name" data-ml-field="First Name" />
    Last Name: <input type="text" id="last_name"  data-ml-field="Last Name"/>
    Email address: <input type="text" id="email"  data-ml-field="Email"/>
    Phone number: <input type="text" id="phone"  data-ml-field="Phone"/>
    Sex: <input type="radio" name="sex" value="male" data-ml-field="Sex"> Male
         <input type="radio" name="sex" value="female" data-ml-field="Sex"> Female
    <input type="submit"/>
</form>

Two important fields that change data are explained below:

After changing the form to more meaningful names the form might be changed to the following to provide more information to MetroLeads:

This will be shown in the Form Manager as below. Much better!

Form with ML Fields

In some cases, due to restrictions that do not allow you to modify the fields but you need several fields to show as one MetroLeads provides a simple naming convention to concatenate such fields. Examples of such non modifiable forms are Wufoo forms.

Country Code: <input type="text" id="field1"/>
Number: <input type="text" id="field2"/>

Lets assume you have a Wufoo form that has the phone field broken into country code and number fields like this: (entire form not shown for brevity)

Captured form:

field1: +1
field2: 4155190000

This will get captured as two fields but what we really need is combined field called Phone. You can modify the form like this:

Country Code: <input type="text" id="field1"  data-ml-field="Phone::1"/>
Number: <input type="text" id="field2" data-ml-field="Phone::2"/>

The format is FieldName::<sequence_number>. The field will be concatenated in sequential order of the sequence number. If any field is empty it will be ignored. In the above example the data submitted will be:

Phone: +14155190000

For phone field and email field, please use "data-ml-field"="phone" and "data-ml-field"="email" for it to be recognizable by Metroleads.

If you want to give the site visitor an option to receive a phone call on form submit, please send a field with "data-ml-field"="mlcallnow" set to true. Ideally this field is associated with a checkbox.

Multiple Lead Capturing Through Single Form

To capture multiple leads via emails or phone numbers, add an attribute data-ml-create-multi="true" to the form element.

<form id="enquiry" action="submit.html" data-ml-form="Contact Us" data-ml-create-multi="true">

And multiple email / phone fields can be handled via the array notation in the field name.

email: <input type="email" name="email" data-ml-field="email[]" /><br />
friends email: <input type="email" name="friendsEmail" data-ml-field="email[]" /><br />

Doing this will make metroleads capture a list for the field email which is represented in code by data-ml-field="email[]".

Any field can be captured as a list of values if an array notation is postfixed to the field name. eg data-ml-field="email[]". This is not limited to emails and phone numbers. This feature is not dependent data-ml-create-multi="true" attribute. The data-ml-create-multi form attribute is specifically to make multiple leads from a single form.

Ajax Integration

Ajax based form submissions are commonly used and due to the nature of the submission it cannot be directly intercepted by MetroLeads. This will be improved in the future. Currently you need to submit the data to MetroLeads via a single function call before submitting the form to your servers. To allow tracking of Ajax forms we have to disable auto form tracking completely.

...
    mg = new MG({}, '<company_id>', '<website_id>');
    mg.init({isAutoTrackForms: false});
...

In automatic form capturing, capturing won’t work if forms are submitted via javascript, in that case, users are suppose to use trackUncommonForm or ajax method to capture the forms as shown in the right column (reason being that “submit” event does not gets fired with javascript form submit http://stackoverflow.com/questions/18774821/submit-event-does-not-fire-if-submit-initiated-programmatically

 

On a single page, we cannot track Ajax and non ajax forms. You must use the same technique presented below to track all forms on such a hybrid page.

And track the form using the following snippet:

function submitForm(){ // attach this function as the event trigger when you want to submit the form
  var form = document.getElementById('demo');
  var formData = form2js(document.getElementById('demo'));
  mg.trackUncommonForm('demo', 'Demo form', formData, function() {
    // Your custom submission code goes here
    onAjaxFormSubmitHandler(); // call the form submit handler function as a callback to mg.trackUncommonForm
  });
}

Multiple Lead Capturing Through AJAX Forms

To track multiple leads through an ajax form as above, you need to add a key-value pair {create_multi: true} in the formData object as above. In such a case, you can pass other identifying form keys as a list, eg {email: [email1, email2]}.

function submitForm(){ // attach this function as the event trigger when you want to submit the form
  var form = document.getElementById('demo');
  var formData = form2js(document.getElementById('demo'));
  formData['create_multi'] = true;
  mg.trackUncommonForm('demo', 'Demo form', formData, function() {
    // Your custom submission code goes here
    onAjaxFormSubmitHandler(); // call the form submit handler function as a callback to mg.trackUncommonForm
  });
}

Ignoring Form Fields From Being Tracked

In order to ignore some fields from being tracked you need to know their identifier or a substring of the identifier, ie the data-ml-field, id or name attribute of the input element. The preference for field naming is done using that order only. Just pass in the name of the fields you want to ignore in the config object passed in mg.init during initialisation.

...
    mg = new MG({}, '<company_id>', '<website_id>');
    mg.init({
      "ignoredFormFields": [fieldName1, fieldName2 ...]
    });
...

The above configuration will make the tracker ignore fields which contain names in the list provided. It is also possible to specify form level filtering. For that change the configuration to something like the following.

...
    mg = new MG({}, '<company_id>', '<website_id>');
    mg.init({
      "ignoredFormFields": {
        _all: [ gField1, gField2 ...],
        'Alpha Form': [alphField1, alphField2 ...],
        'Beta Form': [betaField1, betaField2 ...]
        ...
      }
    });
...

In the above configuration, the tracker will ignore fields mentioned in _all for all the forms processed by tracker. The other filters will be applied per form basis, for instance, the fields mentioned in the Alpha Form will be ignored in the form with name Alpha Form.

the following two configurations are interchangable.

...
    mg = new MG({}, '<company_id>', '<website_id>');
    mg.init({
      "ignoredFormFields": [fieldName1, fieldName2 ...]
    });
...
...
    mg = new MG({}, '<company_id>', '<website_id>');
    mg.init({
      "ignoredFormFields": {
        _all: [fieldName1, fieldName2 ...],
        ...
      }
    });
...

Ignoring Form Fields For AJAX Forms From Being Tracked

There are two approaches to ignore fields for AJAX based submission.

Configuration based

This approach is viable for simple form submission via ajax. By simple we mean where the form object is as is from the inputs and there is no manipulation before submission. The configuration based approach can be applied just like it is done for a simple form. Pass the configuration as mentioned above in the form of a global list of fields, or a map [js object] of list of fields indexed by the name of the forms. And track the form as you do for any ajax based form.

Config:

...
    mg = new MG({}, '<company_id>', '<website_id>');
    mg.init({
      "ignoredFormFields": ...
    });
...

Submission:

function submitForm(){ // attach this function as the event trigger when you want to submit the form
  var form = document.getElementById('demo');
  var formData = form2js(document.getElementById('demo'), 'demo');
  // The second parameter is needed here if you are ignoring fields via config in a ajax submission.
  // The second parameter is the form name. If it is not found then only the global field filters are applied.

  mg.trackUncommonForm('demo', 'Demo form', formData, function() {
    // Your custom submission code goes here
    onAjaxFormSubmitHandler(); // call the form submit handler function as a callback to mg.trackUncommonForm
  });
}

This approach is simpler and gives a greater control over the fields being sent for tracking. You do not need to pass any configuration for this approach. Please follow the example below.

function submitForm(){ // attach this function as the event trigger when you want to submit the form
  var form = document.getElementById('demo');
  var formData = form2js(document.getElementById('demo'));

  // use the delete keyword for removing the unwanted fields
  // Assuming that we have a field in our form which is named unwantedField
  delete formData.unwantedField

  mg.trackUncommonForm('demo', 'Demo form', formData, function() {
    // Your custom submission code goes here
    onAjaxFormSubmitHandler(); // call the form submit handler function as a callback to mg.trackUncommonForm
  });
}

Using the programing approach you have a greater control of the data before sending it for tracking or submission.

Ignoring A Form From Being Tracked

Disable auto form tracking by using the same init code as in the snippet but change the isAutoTrackForms to false

<form id="search" action='search_results.html' ignoretrack="true">
   <input type="text" id="search-text"/>
   <input type="submit">
</form>

Simply add "ignoretrack"="true" for the forms which you do not want to track. For example, a search form

WordPress Integration

For WordPress, we recommend using the Insert Headers and Footers Plugin. The plugin can be used to consistently insert the header above on all pages.

Demos & Sample Code

All of the examples above are available for you to test and directly integrate at https://gist.github.com/kontinuity/486d6d7224d7b2473d87