Installation

Table of contents

  1. Ways to add the code to the page
    1. Google Tag Manager
    2. Directly in the source code
  2. Examples
    1. Form tracking tag
      1. When the form is visible on page load
      2. When the form is not visible on page load
    2. Completion tracking tag
  3. Advanced tracking
    1. Form with no name or id attributes
    2. Form that’s a <div> tag and not a <form>
    3. Forms added to the page after page load (e.g. AJAX)
  4. Tracking custom attributes
  5. Tracking custom events
  6. Checking your installation

Ways to add the code to the page

The code you use to install Zuko will be specific to each form on your site. It’s imperative that each piece of installation code is loaded for the correct form.

Depending on your site, you can choose to install Zuko using a tag manager like Google Tag Manager or insert the code into the HTML.

See the examples section below for examples of the tags that you’ll need to add.

Google Tag Manager

To add the Zuko tags via Google Tag Manager, you’ll first need to create at least the tags from the examples section in Google Tag Manager.

The Form tracking code tags can usually be fired in GTM using the built-in Dom ready trigger, as this is the easiest solution for most users.

If your form is not visible on page load and visitors are required to click a button to open up the form, the form view event will need to be triggered by a custom trigger in GTM.

Directly in the source code

To add Zuko tags directly into the source of your site, your development team will need to add at least the tags from the examples section.

Where on your site these tags will need to be added is specific to each site, but usually the the Form tracking code can be added to the page after your form, before the closing </body> tag.

If your form is not visible on page load and visitors are required to click a button to open up the form, the form view event will need to be executed on the page after the form has been made visible.

Examples

Form tracking tag

Your form may look like this:

<form id="mailing-list-signup">
  <label for="email">Email: </label>
  <input id="email" type="email" />

  <input type="submit">
</form>

When the form is visible on page load

To track this form, ensure that a tag like the following is configured to load in GTM or be added to the page when the page loads:

<script src="https://assets.zuko.io/js/v2/client.min.js"></script>
<script>
  Zuko
    .trackForm({
      target: document.getElementById('mailing-list-signup'),
      slug: 'mailing-list-signup'
    })
    .trackEvent(Zuko.FORM_VIEW_EVENT)
</script>

This tag loads the Zuko library onto the page, starts tracking the form ready for interaction events from the visitor, then sends the form view event.

You will need to change the example for your form:

  • target is the element on the page which represents your form. Read more on form elements here.
  • slug is a string of text used to identify your form within your domain. Read more on slugs here.

When the form is not visible on page load

If your form is hidden from visitors on page load and then shown when they click a button, you will need to delay firing the form view event until your form is visible.

Instead of the above tag, you will need two separate tags:

<script src="https://assets.zuko.io/js/v2/client.min.js"></script>
<script>
  Zuko
    .trackForm({
      target: document.getElementById('mailing-list-signup'),
      slug: 'mailing-list-signup'
    })
</script>

This tag loads the Zuko library onto the page and starts tracking the form ready for interaction events from the visitor.

Then add this tag when the form is made visible to the visitor:

<script>
  Zuko
    .trackForm({slug: 'mailing-list-signup'})
    .trackEvent(Zuko.FORM_VIEW_EVENT)
</script>

Note: The target is not necessary when sending the form view event as no interactions are to be tracked.

This tag uses the Zuko library that is already loaded onto the page, then sends the form view event. The slug is used to identify which form that the visitor has viewed.

Completion tracking tag

A completion event can be fired on a certain URL, page load, or triggered on an event, as long as it accurately represents the point that a visitor has completed your form.

Following on from the above examples, ensure that a tag like the following is configured to fire in GTM or be added to the page when a user has completed your form.

<script src="https://assets.zuko.io/js/v2/client.min.js"></script>
<script>
  Zuko
    .trackForm({slug: 'mailing-list-signup'})
    .trackEvent(Zuko.COMPLETION_EVENT)
</script>

Note: The target is not necessary when sending the completion event as no interactions are to be tracked.

This tag loads the Zuko library onto the page, then sends the completion event. The slug is used to identify which form that the visitor has completed.

You only need to bring in the Zuko library if your Completion tracking tag is fired on a different page to the Form tracking code tags.

Advanced tracking

Form with no name or id attributes

A form with no name or id HTML attributes can be tracked by Zuko, provided that you have a reliable way to target the form element on the page.

For example, your form may have a HTML class of checkoutForm:

<form class="checkoutForm">
  <label for="email">Email: </label>
  <input id="email" type="email" />

  <input type="submit">
</form>

You could use the following code to track the form, assuming that there are no other elements on the page which have this class:

<script src="https://assets.zuko.io/js/v2/client.min.js"></script>
<script>
  Zuko
    .trackForm({
      target: document.getElementsByClassName('checkoutForm')[0], // Here we assume the first element with the class of checkoutForm is the form
      slug: 'checkoutForm'
    })
</script>

Note: Multiple elements on the page may have the same class, so this isn’t a reliable way of targeting a form.

Alternatively, when the surrounding elements are specific to your form:

<div class="container">
  <div class="mainContent">
    <form class="signup">
      <label for="email">Email: </label>
      <input id="email" type="email" />
    
      <input type="submit">
    </form>
  </div>
</div>

A CSS selector can be used to target a particular element:

<script src="https://assets.zuko.io/js/v2/client.min.js"></script>
<script>
  Zuko
    .trackForm({
      target: document.querySelector('.container .mainContent form.signup'), // A signup form inside the mainContent container
      slug: 'checkoutForm'
    })
</script>

Form that’s a <div> tag and not a <form>

If your form isn’t a standard <form> element, Zuko can still track the form, just as if it’s a form with no name or id attributes.

Forms added to the page after page load (e.g. AJAX)

For forms which are loaded in after the page has loaded, for example a form which is added to the page after an AJAX request has succeeded, you will need to ensure you execute the Zuko.trackForm() function when you determine that your target element has been loaded.

Please see our browser JavaScript library documentation for specific guidance on the Zuko.trackForm() function.

Tracking custom attributes

A custom attribute can be set on a visitor’s session to allow you to group your sessions into segments.

A custom attribute consists of two strings which represent a key-value relationship. For example, key: source, value: google.

Custom attribute values are not intended to be completely unique, they should represent a group of visitors.

Note: Both the key and value must not contain any spaces, use only alphanumeric characters and are limited to 85 characters long.

Custom attributes may be present for the visitor’s session when form tracking starts. In which case you can chain the setAttribute method onto the trackForm method, before the form view event is sent.

<script src="https://assets.zuko.io/js/v2/client.min.js"></script>
<script>
  Zuko
    .trackForm({
      target: document.getElementById('mailing-list-signup'),
      slug: 'mailing-list-signup'
    })
    .setAttribute('source', 'Google')
</script>

Custom attributes may also become available during the visitor’s session depending on what the visitor selects in the form, or depending on other factors that change during a session.

An attribute’s value may be set and re-set multiple times within a session. However, only the last value of the attribute only will be stored against the session.

<script src="https://assets.zuko.io/js/v2/client.min.js"></script>
<script>
   var signUpZukoClient = Zuko
    .trackForm({
      target: document.getElementById('mailing-list-signup'),
      slug: 'mailing-list-signup'
    })
    .setAttribute('source', 'Google')
</script>

Later on, the selected value of the houseSelect field can be stored against the current visitor:

<script>
  // Setting the houseType attribute when a visitor changes the field
  document
    .getElementById('houseSelect')
    .addEventListener('change', function (e) {
        signUpZukoClient
          .setAttribute('houseType', e.target.value)
    })
</script>

Tracking custom events

A custom event represents a specific type of event that your visitor encountered during their session on your form.

A custom event consists of an object with a type property, which is a simple short string describing the event.

It is recommended to keep the custom event type relatively short (40-50 characters), to make them easy to identify in visualisations in the Zuko app.

The trackEvent() function should be called at the point at which the event occurs.

<script src="https://assets.zuko.io/js/v2/client.min.js"></script>
<script>
  Zuko
    .trackForm({
      target: document.getElementById('mailing-list-signup'),
      slug: 'mailing-list-signup'
    })
</script>

When your validation detects the field is invalid, the custom event can be fired:

<script>
  // After the field has been interacted with
  if (!emailField.valid()) {
    Zuko
      .trackForm({slug: 'mailing-list-signup'})
      .trackEvent({type: 'Error_email-field-is-invalid'})
  }
</script>

Checking your installation

Once your installation is complete you can view events being sent to Zuko in the network tab of your browser

Here the Zuko JavaScript library had successfully loaded on the form page:

Loaded library

A form view event is sent to Zuko:

Form view event sent to Zuko

An interaction event is sent to Zuko:

Interaction event sent to Zuko

A completion event is sent to Zuko:

Completion event sent to Zuko