Link Search Menu Expand Document

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. Changing the identity of a field by overriding it’s HTML attributes
    5. Tracking fields that are not a supported element
  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: 'caba1457c8fa6b78'
    })
    .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 required form view event.

Note: Your visitor’s data can only be viewed in the Zuko app when the form view event is received, so make sure that .trackEvent(Zuko.FORM_VIEW_EVENT) is included in this tracking tag.

In Zuko.trackForm(), 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: 'caba1457c8fa6b78'
    })
</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: 'caba1457c8fa6b78'})
    .trackEvent(Zuko.FORM_VIEW_EVENT)
</script>

This tag uses the Zuko library that is already loaded onto the page, then sends the required form view event.

Note: Your visitor’s data can only be viewed in the Zuko app when the form view event is received, so make sure that .trackEvent(Zuko.FORM_VIEW_EVENT) is included when the form is visible.

In Zuko.trackForm(), the slug is used to identify which form that the visitor has viewed.

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

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: 'caba1457c8fa6b78'})
    .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 when visible on page load, 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'
    })
    .trackEvent(Zuko.FORM_VIEW_EVENT)
</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'
    })
    .trackEvent(Zuko.FORM_VIEW_EVENT)
</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() and trackEvent(Zuko.FORM_VIEW_EVENT) functions when you determine that your target element has been loaded.

Please see our browser JavaScript library documentation for specific guidance on the Zuko.trackForm() and trackEvent(Zuko.FORM_VIEW_EVENT) functions.

Changing the identity of a field by overriding it’s HTML attributes

Zuko uses a field’s tagName, type, name and id HTML attributes to create an identity for a field. It combines these four pieces of information into one identifier. If one of these attributes changes, Zuko will see it as a different field.

Sometimes, you may want to control the identity of a field. For example, you may want to show a number input to mobile users and a normal text field to desktop users:

<input type="number" name="zipCode">
<input type="text" name="zipCode">

In the above example, Zuko would track interactions with two separate ZIP code fields, depending on which version is rendered to your visitor by your site.

With a little tweak to the form in the HTML, Zuko allows interactions on the two fields to be tracked as one:

<input type="number" name="zipCode" data-zuko-type="number">
<input type="text" name="zipCode" data-zuko-type="number">

The data-zuko-type attribute instructs Zuko to override the tracked type attribute to have a value of number, meaning that interactions with both versions of the field are processed by Zuko as the visitor interacting with one field:

<input type="number" name="zipCode">

Zuko allows all four of the identifying HTML attributes (tagName, type, name and id) to be overridden in the same way:

<input data-zuko-tag-name="button">
<input data-zuko-type="number">
<input data-zuko-name="email">
<input data-zuko-id="email">

Tracking fields that are not a supported element

Sometimes, you may want to track your visitors interacting with an element that is not supported by Zuko out of the box.

For example, you may have a <div> that’s rendered as a button:

<div class="button">

Using the same method as overriding the identity of a field, you can override the tagName that Zuko uses in identifying this element, so that interactions with it can be tracked as if it was with a supported element:

<div data-zuko-tag-name="button" data-zuko-name="submitButton" class="button">

Zuko would track clicks on this element as clicks on a button that looks like this:

<button name="submitButton" class="button">

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: page_variant, value: a.

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

Note: Both the key and value 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() function onto the Zuko.trackForm() function, before the required 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: 'caba1457c8fa6b78'
    })
    .setAttribute('page_variant', 'a')
    .trackEvent(Zuko.FORM_VIEW_EVENT)
</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. In this case an instance of Zuko tracking needs to be assigned to a variable to be used for assigning attributes later.

In this example the selected value of the houseSelect field is set for the visitor’s session.

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

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

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.

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. For example, type: Email field invalid.

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

Here form tracking is started and the required 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: 'caba1457c8fa6b78'
    })
    .trackEvent(Zuko.FORM_VIEW_EVENT)
</script>

Then, when your validation detects a field is invalid, the custom event can be fired:

<script>
  // After the field has been interacted with
  if (!emailField.valid()) {
    Zuko
      .trackForm({slug: 'caba1457c8fa6b78'})
      .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