Track Klaviyo form activity using JavaScript

❗️

This guide refers to Klaviyo's v1/v2 legacy APIs.

We are in the process of updating these guides, please check back later! For more information about the differences between legacy and new APIs, check out the comparison chart and [new API overview] (ref:api_overview).

Klaviyo form events 

Klaviyo forms send an event called klaviyoForms to the window each time activity occurs on a form. The general structure of the Klaviyo form event is:

var event = new CustomEvent("klaviyoForms", {
    detail: {
        type: 'submit',
        formId: 'F12345',
        companyId: 'C12345', 
        metaData: { 
            g: '12345',
            $email: '[email protected]',
        } 
    }});
window.dispatchEvent(event);

Form event types

The type field in the event details can contain one of the following six event types:

• open
  This event fires when a popup or flyout form initially displays on a page
• embedOpen
  This event fires when an embedded form loads on a page
• close
  This event fires when a visitor closes a form
• redirectedToUrl
  This event fires when a visitor clicks a button on a form that is set to redirect them to a URL 
• submit
  This event fires when a visitor submits the main conversion action of a form (e.g., the first email or SMS subscription action), and will only fire once per form 
• stepSubmit
  This event fires when each step is submitted, and can fire multiple times per form 

When choosing which event to use, consider what you’re trying to track. If you are tracking general form analytics (e.g., tracking form submissions in Google Analytics), use submit, which only fires once per form. If your goal is passing detailed data to a third party, use stepSubmit so all submitted data is captured.

Submit events: submit vs. stepSubmit 

The stepSubmit event fires every time a step is submitted, and can fire multiple times for the same form. For a multi-step form, the submit event fires just once per form, following these criteria: 

• For forms with email or SMS subscription actions, submitting an email or phone triggers a submit event
• For forms containing both email and SMS fields across multiple steps, submitting whichever appears first in the form triggers a submit event
• For forms without an email or SMS subscription action (e.g., a form containing only text fields), clicking a button with the Action set to Submit Form triggers a submit event

Additional event details 

In addition to the event type, the event details include the following: 

• formID
  The ID of the form, which can be found in the form’s URL within Klaviyo. This is a six-character alphanumeric code and uniquely identifies each form in Klaviyo.
• companyId
  Your account's unique six-character public API key. 
• metaData
  Data related to each unique submit or stepSubmit event. This field contains all of the fields submitted to Klaviyo.
  • g
    The unique ID of the list linked to the form. For example, if your welcome popup is set to submit new subscribers to your newsletter list, this would be the ID that is included in the event.
  • $email
    The email address of the person who submits the form, if submitted through the current form.
  • $phone_number
    The phone number of the person who submits the form, if submitted through the current form.
  • stepName
    The metadata of stepSubmit events will include the step's name. 
  • Additional Fields
    Any additional fields unique to the particular form will appear beneath the $email value.

Structure of an event listener

Below, you'll find the general structure you should use when creating your own custom event listener. The field open can be changed to any other form event, depending on your use case. Replace Custom JS with the JavaScript that should run when the event occurs. 

<script>
    window.addEventListener("klaviyoForms", function(e) { 
        if (e.detail.type == 'open') {
            Custom JS 
        }
    });
</script>

To reference the event’s timestamp in your custom JavaScript, use e.timeStamp. 

Example use cases

Google Analytics tracking on submit

Track an event in Google Analytics when someone submits a specific form.

<script>
    window.addEventListener("klaviyoForms", function(e) { 
        if (e.detail.type == 'submit') {
            ga('send', 'event', 'Klaviyo form', 'form_submit', e.detail.formId);
        }
    });
</script>

Redirect to another page based on which radio button they selected

Redirect subscribers to another page when they submit a form after selecting a specific radio button on a form. In the example below, coffee is one button and tea is another. These buttons submit to the profile property department.

<script>
    window.addEventListener("klaviyoForms", function(e) {
        if (e.detail.type == 'submit') {
            switch (e.detail.metaData.department) {
            case 'coffee':
            window.location.replace('/coffee');
            break;
            case 'tea':
            window.location.replace('/tea');
            break;
            }
        }
    });
</script>

Update a profile property on open

This can be useful if you would like to attach or update a profile property to a browser when a customer is shown a specific form. Note that only identified visitors (i.e., those who were cookied when they viewed the form, or who filled out the form) can have their profiles updated using this method. 

<script>
    var _learnq = window._learnq || [];
    window.addEventListener("klaviyoForms", function(e) { 
        if (e.detail.type == 'open') {
            _learnq.push(['identify', {
                'shownHomepageForm' : 'true',
            }]);
        }});
</script>

Track form views and submissions for tracked profiles

While Klaviyo form analytics are not tied to profiles (so that you can measure conversion rates), you can trigger your own form view and submission events that are tied to profiles. This can be useful if you want to build segments based on who has seen or submitted a form.

<script>
    var _learnq = window._learnq || [];
    window.addEventListener("klaviyoForms", function(e) { 
        if (e.detail.type == 'open' || e.detail.type == 'embedOpen') {
            _learnq.push(['track', 'Viewed Form - Tracked Profile', {
                'formId' : e.detail.formId
            }]);
        }
        if (e.detail.type == 'submit' || e.detail.type == 'redirectedToUrl') {
            _learnq.push(['track', 'Submitted Form - Tracked Profile', {
                'formId' : e.detail.formId
            }]);
        }
    });
</script>