Form tracking

Form tracking can track all manners of form input. A list of measured forms can be called up in the Mapp Q3 tool under Navigation > Forms.

Methods and properties

name

Get the name of the extension.

/**
 * @type {string}
 */
wtSmart.extension.form.name;

version

Get the version of the extension.

/**
 * @type {string}
 */
wtSmart.extension.form.version;

config

Set and get the current configuration of the extension.

• attribute: By default, your form's "data-name" attribute is used to generate its name. With the property "attribute" you can define another attribute (e.g. the "id" or "name" attribute) as the form identifier. The attribute is mandatory in every form request.
• shadowRoot: If you use web components (shadow DOM elements) on your website where you want to enable action tracking, you can do this via the 'shadowRoot' property. For this you can specify all CSS selectors of your shadow DOM elements to be tracked.
• automatic: By default, automatic form tracking is deactivated. There are two ways to enable automatic form tracking:
  

  1. automatic = true. You can set [automatic] to "true". In that case, the pixel checks the HTML <form> tag and the specified attribute (form[${config['attribute']}]) to detect and track forms.

  2. automatic = "CSS Selector". You can specify a respective CSS selector to specify which forms to track (e.g. "form[name]" for all form elements with the "name" attribute).

• fullContent: All form fields are measured, with the exception of the "hidden", "button", "image", "reset" and "submit" field types. With the form field types "select-multiple", "select-one", "checkbox" and "radio", the precise values can be transmitted. With all other form field types, only the field status is sent to Mapp Intelligence, i.e. only "filled_out" is sent for a completed form field and not the content. If, however, you would like to evaluate the form field content as clear text, add the corresponding form fields to the configuration property "fullContent".
• anonymous: If required, you can anonymise all form data – for data protection reasons, for example – before sending it to Mapp Intelligence. This means content from the form fields will not be transmitted. The Mapp Intelligence screen will therefore only show which form fields were completed and which were not.
• pathAnalysis: Using the path-view you can display the timely order of objects, in this case form-field objects. This enables you to analyze the order in which form-fields were selected. form-fields will be tracked more than once if they were selected multiple times. If you want to enable this feature, please set the according property "pathAnalysis".
• field: Contains the configuration for form fields.
  • attribute: By default, your form fields "data-name" attribute is used to generate its name. With the property "attribute" you can define another attribute (e.g. the "id" or "name" attribute) as the form field identifier.
  • value: For form fields of the type "radio," "select-one," "select-multiple" and "checkbox", the value of the "value" attribute will be sent to Mapp Intelligence by default. Optionally, an alternative value attribute could be used. If the alternative attribute is set, the value of all of the above-mentioned field types in the alternative attribute will be sent. This is helpful if you are only sending an ID as the standard value, and this would not be understandable for your web analysts when using the Mapp Intelligence tool.
  • defaults: If you would like to track forms that have been pre-filled with a default value, you must inform the Smart Pixel of which form fields are concerned. This is done with the property "defaults". This includes an object with a mapping between form field names and form field default values.

/**
 * @typedef {
 *      selector: string,
 *      [attribute="data-name"]: string,
 *      [automatic=false]: boolean|string,
 *      [fullContent=[]]: string[],
 *      [anonymous=false]: boolean,
 *      [pathAnalysis=false]: boolean,
 *      [field]: {
 *          [attribute="data-name"]: string,
 *          [value="value"]: string,
 *          [defaults={}]: {[string]: string}
 *      }
 * } SmartPixelExtensionFormShadowRoot
 */

/**
 * @param {{
 *      [attribute="data-name"]: string,
 *      [shadowRoot]: string[]|SmartPixelExtensionFormShadowRoot[],
 *      [automatic=false]: boolean|string,
 *      [fullContent=[]]: string[],
 *      [anonymous=false]: boolean,
 *      [pathAnalysis=false]: boolean,
 *      [field]: {
 *          [attribute="data-name"]: string,
 *          [value="value"]: string,
 *          [defaults={}]: {[string]: string}
 *      }
 * }} [config]
 *
 * @returns {object}
 */
wtSmart.extension.form.config(config);

add

Activate form tracking for this form.

/**
 * @param {HTMLFormElement|CustomForm} form
 */
wtSmart.extension.form.add(form);

update

The forms contained in page content reloaded by Ajax (e.g. when showing layers) can also be marked for automatic form tracking. To do this, call the "update" method as soon as new content is reloaded.

wtSmart.extension.form.update();

get

Get the status, if the form tracking is enabled.

/**
 * @param {HTMLFormElement|CustomForm} form
 *
 * @returns {HTMLFormElement|CustomForm|boolean}
 */
wtSmart.extension.form.get(form);

remove

Remove form tracking for this form.

/**
 * @param {HTMLFormElement|CustomForm} form
 */
wtSmart.extension.form.remove(form);

send

Send form tracking request manually for this form.

/**
 * @param {HTMLFormElement|CustomForm} form
 */
wtSmart.extension.form.send(form);

submit

Change the internal form status to "submitted".

/**
 * @param {HTMLFormElement|CustomForm} form
 */
wtSmart.extension.form.submit(form);

getAll

Get all initialized forms.

/**
 * @returns {HTMLFormElement[]|CustomForm[]}
 */
wtSmart.extension.form.getAll();

removeAll

Remove all initialized forms.

wtSmart.extension.form.removeAll();

sendAll

Send all initialized forms manually.

wtSmart.extension.form.sendAll();

Example

// set form tracking config
wtSmart.extension.form.config({
    attribute: 'data-wt-name',
	automatic: true,
    fullContent: ['plz', 'firstname', 'lastname'],
    anonymous: true,
    pathAnalysis: true,
    field: {
        attribute: 'data-wt-name',
        value: 'data-wt-value',
        defaults: {
            firstname: 'Firstname',
            lastname: 'Lastname'
        }
    }
});

// activate automatic form tracking - boolean
wtSmart.extension.form.config({
    automatic: true
});

// activate automatic form tracking - selector
wtSmart.extension.form.config({
    automatic: 'div[data-my-custom-form]'
});

// get form tracking config
var formConfig = wtSmart.extension.form.config();

// activate form tracking for the first form
wtSmart.extension.form.add(document.forms[0]);

// is the first form initialized
var isInitialized = wtSmart.extension.form.get(document.forms[0]);

// change the internal form status to "submitted" for the first form
wtSmart.extension.form.submit(document.forms[0]);

// send form tracking request manually for the first form
wtSmart.extension.form.send(document.forms[0]);

// remove form tracking for the first form
wtSmart.extension.form.remove(document.forms[0]);

/* *********************************************** */
/* ************* multi form tracking ************* */
/* *********************************************** */

// activate form tracking for some forms
wtSmart.extension.form.add(document.forms[0]);
wtSmart.extension.form.add(document.forms[1]);
wtSmart.extension.form.add(document.forms[2]);
wtSmart.extension.form.add(document.forms[3]);

// get all initialized forms
var initializedForms = wtSmart.extension.form.getAll();

// send all initialized forms
wtSmart.extension.form.sendAll();

// remove all initialized forms
wtSmart.extension.form.removeAll();