This guide explains how to use JavaScript event listeners to respond to visitor interactions with Omnisend forms. With event listeners, you can:
⚠️ Important: Event listeners work on popup, flyout, and embedded forms. They are not supported on Omnisend landing pages at this time.
Before You Begin
The Omnisend JavaScript snippet must already be installed on your site. Without it, the
omnisendFormsevent will not fire, and your listener will never execute. On Shopify and WooCommerce, the snippet is added automatically. On any other platform, add it manually before the closing</body>tag on every page where your form appears.You only need one snippet per page. One Omnisend script enables all forms, tracking, and event listening. If you have both an embedded form and an event listener on the same page, a single snippet covers both.
For Google Analytics integration: Your GA4
gtagscript must already be loading on the page before the Omnisend event listener fires. Ifgtagis not present when the listener runs, the GA4 event will not be sent.
Form Events
Omnisend forms trigger an event named omnisendForms on the window object whenever there is activity on a form. The example below shows the event payload
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– fires when a popup, flyout, or embedded form initially displays on a page.interaction– fires once when the user interacts with the form (for example, selects an input field).submit– fires once when a visitor completes the primary conversion action (for example, the initial email or SMS subscription).close– fires when a visitor closes the form.stepView– fires each time a step of a multi-step form is displayed; can fire multiple times per form.stepInteraction– fires once per step when the user interacts with a multi-step form.stepSubmit– fires each time a step of a multi-step form is submitted; can fire multiple times per form.
Choose the event type based on your specific tracking needs. For general form analytics such as tracking form submissions in Google Analytics, use submit – it fires only once per form. For multi-step forms, also capture step data using stepSubmit.
Step Events
Step events fire only with multi-step forms. The stepSubmit event fires whenever a step is submitted and can fire multiple times for the same form. For a multi-step form, the submit event fires once per form, after all steps are completed.
Other Event Details
In addition to the event type, the event detail object contains:
brandID– the alphanumeric ID that uniquely identifies your brand in Omnisend.step– the step in which the event occurred. Applicable only for multi-step forms.form– data related to the form, including:id– the alphanumeric ID that uniquely identifies the form.name– the name of the form.displayType– the form display type (popup, flyout, or embedded).versionId– the alphanumeric ID that uniquely identifies an A/B form version.versionName– the name of the A/B form version.
formValues– all form fields and their submitted values, including:emailField,firstName,lastName,phoneNumberCountryCodeField,phoneNumberField, and any other custom form field.
Execute Custom JavaScript Upon Event Occurrence: Event Listener Sample
The following is the standard format for a custom event listener for Omnisend form events. Replace view with any event type listed in the Form Event Types section above, and replace // Custom JS with the code that should run when the event fires.
<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.
Where to add this script:
Shopify: Paste the code in your theme's footer or layout file (for example,
theme.liquid), before the closing</body>tag, so it loads on every page where the form can appear.WordPress / WooCommerce: Add it using a Custom HTML block in your page editor, or paste it into your theme's footer file before
</body>.Plain HTML: Paste it before the closing
</body>tag on every page where the form appears.
Implement Google Analytics Tracking on Form Events
Use the following snippet to track each Omnisend form event type as an event in Google Analytics (GA4).
Note: Your GA4 gtag initialization script must already be loading on the page before this snippet runs. If gtag is not present when the listener fires, the GA4 events will not be recorded.
<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>
Note: The event names in the gtag('event', ...) call – for example, omnisend_form_submit – can be renamed to anything you want to appear in Google Analytics, such as newsletter_signup or popup_completed. The name is entirely up to you.
FAQ
Do I need to add the event listener to my Shopify theme?
Yes. Paste the listener code into a globally loaded location in your Shopify theme – for example, your theme.liquid footer – so it runs on every page where the form can appear. Place it before the closing </body> tag.
Does the Omnisend plugin need to be installed for this to work?
Not necessarily. The Omnisend plugin (on Shopify or WooCommerce) installs the Omnisend JS snippet automatically. On any other platform, you need to add the snippet manually. The snippet itself is the requirement – not the plugin.
How can I track at which step visitors abandon my multi-step popup?
Listen for the close event and read e.detail.step. A value of 2 means the visitor closed the popup while on step 2. Send this as a custom parameter in your gtag call or log it in any other analytics tool.
Can I capture which button a visitor clicked (for example, "Yes" or "No")?
No. The omnisendForms event payload does not include button text. To associate a button label with your tracking event, hardcode it manually in your listener code.
Do I need to add the Omnisend snippet more than once for multiple forms on a page?
No. One snippet per page is enough for all forms, tracking, and event listeners on that page.
Have trouble figuring this out? Message our 24/7 support team in-app or email [email protected].