This guide will cover how to use event listeners to trigger custom JavaScript based on site visitor interaction with a form to learn about their behavior. It enables the following features:
Form Events
Omnisend forms trigger an event named 'omnisendForms' on the window whenever there is an activity on a form.
Please check the object for an example of the event payload below ⤵️
const event = new CustomEvent("omnisendForms", {
detail: {
eventName: 'submit',
brandID: 'F12345',
form: {
id: 'F12345',
name: 'F12345',
displayType: 'popup',
versionID: 'F12345',
versionName: 'F12345',
},
formValues: {
emailField: '[email protected]',
phoneNumberCountryCodeField: 'US',
phoneNumberField: '11111111',
firstName: 'Name',
lastName: 'LastName',
//... any other form value
}
}
});
window.dispatchEvent(event);
Form Event Types
The type field within the event object can be any of these seven distinct events:
view
This event fires when a popup, flyout form, or embedded form initially displays on a page.
interaction
This event fires when the user interacts with the form (e.g., selects the input field), and it fires only once for each form.
submit
This event fires upon a visitor completing the primary conversion action in a form (for example, the initial email or SMS subscription) and it will fire only once for each form.
close
This event fires when a visitor closes a form.
stepView
This event fires when each step of the multi-step form is displayed on a page, and it can fire multiple times per a form.
stepInteraction
This event fires when the user interacts in a multi-step form (e.g., selects input field); it fires once per step.
stepSubmit
This event fires when each step of the multi-step form is submitted, and it can fire multiple times per a form.
When picking the perfect event to use, you must consider the specific tracking needs.
If you are looking at general form analytics, such as tracking form submissions in Google Analytics, choose the 'submit' event; it triggers only once per a form. If you have a multi-step form, you can additionally capture step data using the 'stepSubmit' event.
Step Events
Step events are fired only with multi-step forms. The 'stepSubmit' event fires whenever a step is submitted and can fire multiple times for the same form. However, for a multi-step form, the submit event fires once per a form.
Other Event Details
Aside from the type of event, the event detail object contains the following information:
brandID
The ID of the brand. This is an alphanumeric code and uniquely identifies each brand in Omnisend.
step
Step in which the event occurred. Applicable only for the multi-step forms.
form
Data related to form, including:
id
The ID of the form. This is an alphanumeric code and uniquely identifies each form in Omnisend.
name
The name of the form.
displayType
The display type of the form (e.g., popup, flyout, embedded).
versionId
This is an alphanumeric code and uniquely identifies each A/B form in Omnisend.
versionName
The name of the A/B form.
formValues
This field contains all of the fields and their values submitted to Omnisend:
emailField, firstName, lastName, phoneNumberCountryCodeField, phoneNumberField, all form`s fields with values.
Execute Custom JavaScript Upon Event Occurrence: Event Listener Sample
The following is the typical format to use when developing your personalized event listener for form events. If needed, you have the option to modify the type view to any other type of form event (as listed in the Form event types section above).
Replace 'Custom JS' in the example below with JavaScript, which should run when the event occurs.
<script>
window.addEventListener("omnisendForms", function(e) {
if (e.detail.type == 'view') {
// Custom JS
}
});
</script>
To utilize the event's timestamp in your own JavaScript code, use 'e.timeStamp'.
Please note that in this use case, the only exception is landing pages. We will also trigger JavaScript events for landing pages; however, event listeners are not possible in landing pages yet.
Implement Google Analytics Tracking on Form Events
Track a specific form event as an event in Google Analytics.
<script>
window.addEventListener("omnisendForms", function(e) {
if (e.detail.type == 'view') {
gtag('event', 'omnisend_form_view', { form_name: e.detail.form.name, form_id: e.detail.form.id });
}
if (e.detail.type == 'interaction') {
gtag('event', 'omnisend_form_interaction', { form_name: e.detail.form.name, form_id: e.detail.form.id });
}
if (e.detail.type == 'submit') {
gtag('event', 'omnisend_form_submit', { form_name: e.detail.form.name, form_id: e.detail.form.id });
}
if (e.detail.type == 'close') {
gtag('event', 'omnisend_form_close', { form_name: e.detail.form.name, form_id: e.detail.form.id });
}
if (e.detail.type == 'stepView') {
gtag('event', 'omnisend_form_step_view', { form_name: e.detail.form.name, form_id: e.detail.form.id });
}
if (e.detail.type == 'stepInteraction') {
gtag('event', 'omnisend_form_step_interaction', { form_name: e.detail.form.name, form_id: e.detail.form.id });
}
if (e.detail.type == 'stepSubmit') {
gtag('event', 'omnisend_form_step_submit', { form_name: e.detail.form.name, form_id: e.detail.form.id });
}
});
</script>