Form tracking

Measure form interactions

The Form Event API provides a way to measure information about the use of forms down to field level, which is included in the form analysis report.

Prerequisites

1. To be able to use the Form Event API, you need an etracker analytics Pro or Enterprise Edition.
2. The tracking code is integrated on the page on which a form event is to be triggered.

Structure of forms

The forms to be measured require a unique name, which is transferred to etracker to ensure correct allocation. A form can be divided into several sections. These sections correspond, for example These sections correspond, for example, to a single page in a multi-page order form or a new tab that opens when, for example, preconditions (such as the correct completion of certain fields) have been met. Just like the form name, the section name within the form is also a unique identifier. A section can contain one or more form fields. Here too, identification within a section is carried out using a unique form field name. The individual pieces of information to be transferred are described in more detail below.

Structure of the functions

The function call generally follows the following pattern:

etForm.sendEvent(<eventType>, <formName>[,<formEventData>]);

Here, eventType indicates what kind of form event it is. The name under which the form appears in the report is entered under formName. The formEventData field contains further information that may only be transferred for certain event types.

etForm.sendEvent(<eventType>, <formName>);

Possible event types

formView

With formView, information is passed on to etracker that a specific form has been viewed. This event should always be triggered when a visitor initially calls up the form. A form always has a unique name, the value of which is transferred with the formName key. This name can be used to identify the form in the report. General form of the call:

etForm.sendEvent('formView', <formName>);

This can also happen several times during a visit if the visitor re-enters the form at the time you have specified. Sending a formView creates a form impression in the corresponding report. If the visitor can re-enter the already processed form during their visit, the website operator must decide whether this is a new form impression for them (and then create another formEvent of type formView with this form name). Example call:

etForm.sendEvent('formView', 'Bestellformular');

In this case, a form impression is created for the form with the name order form.

formFieldsView

With a formFieldsView, information about the fields that the website visitor has seen and the section in which these fields are located is transferred to etracker. A form consists of one or more sections. The individual section should always have a unique name per form, the value of which is transferred with the key sectionName. A section can contain one or more form fields. These form fields are stored in an array with the name sectionFields is passed. A form field is created as an object within the array of sectionFields transferred. The object has two properties: name and type. The form field should always have a unique name within the section, the value of which is specified in the name is passed. Furthermore, it always has a type that is transferred in the type property. A string describing the type of the form field is expected as the type. We recommend specifying a string representation of the corresponding HTML form element type. However, you can also use your own identifier as the form type.

etForm.sendEvent('formFieldsView', <form_name>,
     {
           'sectionName': <section_name>,
           'sectionFields':
                 [
                       {'name': <field_name>,'type': <field_type>},
                       ...
                       {'name': <field_name>,'type': <field_type>}
                 ]
     }
     );

This call transfers the information to etracker that the website visitor has seen the section with the name <section_name> and the fields specified in sectionFields .

etForm.sendEvent('formFieldsView', 'Kontaktformular',
     {
           'sectionName': 'Adressangaben',
           'sectionFields':
                 [
                       {'name': 'Anrede', 'type': 'radio'},
                       {'name': 'Vorname','type': 'text'},
                       {'name': 'Nachname','type': 'text'}
                 ]
     }
     );

formFieldInteraction

The event type formFieldInteraction can be used to transfer information to etracker that a specific field has been interacted with.

etForm.sendEvent('formFieldInteraction', <form_name>,
     {
           'sectionName': <section_name>,
           'sectionField': {'name': <field_name>,'type':
<field_type>}
     }
     );

So if the website visitor has interacted with the checkbox Salutation in the Address Data section of the order form (for example, has selected ‘Mr.’ by clicking on it), the corresponding call to etracker could read like this:

etForm.sendEvent('formFieldInteraction', 'Bestellformular',
     {
           'sectionName': 'Adressdaten',
           'sectionField': {'name': 'Anrede','type': 'checkbox'}
     }
     );

An interaction for this form field, this section and this form is then counted in the corresponding report.

formFieldError

The event type formFieldError can be used to transfer information to etracker that an error has occurred in a specific field.

etForm.sendEvent('formFieldError', <form_name>,
     {
           'sectionName': <section_name>,
           'sectionField': {'name': <field_name>,'type':
<field_type>}
     }
);

So if the website visitor has generated an error in the order form in the address data section in the text input last name (for example, has left a required field empty), the corresponding call to etracker could read like this:

etForm.sendEvent('formFieldError', 'Bestellformular',
     {
           'sectionName': 'Adressdaten',
           'sectionField': {'name': 'Nachname','type': 'text'}
     }
);

An error is then counted for this form field, this section and this form in the corresponding report.

formConversion

The event type formConversion can be used to transfer information to etracker that a specific form has been successfully submitted. In general, the call looks like this:

etForm.sendEvent('formConversion', <form_name>);

If the website visitor has successfully completed and submitted the form in the order form (e.g. by clicking on the ‘Buy now’ button), the corresponding call to etracker could read as follows:

etForm.sendEvent('formConversion', 'Bestellformular');

Exemplary implementation

The events should always be sent to etracker when the corresponding action has been triggered, e.g. by the website visitor. The formView Event can be triggered, for example, when the website visitor clicks on the link that opens the corresponding form:

<a href="bestellformular.html" onmousedown="etForm.sendEvent
('formView', 'Bestellformular');"> Zum Bestell-Formular
</a>

In this case, a formView with the form name order form is recorded for etracker as soon as the customer clicks on the link to the order form. The formView event can also be triggered when a page containing a form is loaded or when a form appears in the visible area of the page being viewed.