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:
Visits
Clicks
Page Bounces
Forms
And will allow to track in the next version:
Downloads
Map views
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:
You wish to have advanced control over the data being sent
When it is submitted the following data is shown in the Form Manager of MetroLeads:
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.
Two important fields that change data are explained below:
data-ml-form Set the form name which will be displayed in MetroLeads
data-ml-field Set the field name as it will be displayed in MetroLeads
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!
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:
The format is FieldName<delimiter><sequence_number> e.g. Phone.1. 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
NOTE: If your field names contain . and want to change the delimiter, you need to add the custom delimter to form2js call.
var formData = form2js(document.getElementById('demo'), 'Form Name', '::');
In the above case, we have used a custom delimiter :: so the HTML code for form fields will be:
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.
Creating notes from Form Fields
A field that needs to be converted to a note should be suffixed by _mlnote.
e.g.
<textarea id="Message_mlnote"></textarea>
Message will be converted into a note and shown in the timeline above the web capture event.
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.
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});
...
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.
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.
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.
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.
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
});
}
Code based [Recommended]
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
