Form Tracking API

From Genesys Documentation
Jump to: navigation, search
This topic is part of the manual Journey JavaScript SDK for version Current of Altocloud.

Learn how to use an API to track form submission and abandonment events, including what visitors enter in your forms.

Related pages:

About the Form Tracking API

In order to track customer activities on your website, you must first deploy the tracking snippet. After you do that, you can track form-level activity with the Form tracking API.

In order to be tracked, a form must have an ID, name, or action field that uniquely identifies it. By default, the values of the input, select, and textarea elements entered in the form (fields with personal information such as name, email, phone number and company name) are sent with the form submission and abandoned events. The customer profile is updated accordingly upon form submission.

Important
You can use Altocloud to track visitor activity in a GDPR compliant-manner, however, you must modify the tracking snippet in order to be compliant. For more information on how to be compliant with the GDPR requirements, see GDPR.


Enable form tracking

To enable form tracking, call forms:track and specify the CSS selector of the form(s) that you want to track. For example:

ac('forms:track', '.hs-form');

To enable tracking for all forms call the function without specifying the selector. For example:

ac('forms:track');

To enable tracking for multiple forms based on the CSS selector specify a group of selectors as a comma-separated list. For example:

ac('forms:track', '#firstFormId, #secondFormId');
Important
Where the same selector is applied to multiple forms, each form with that selector will be tracked separately.
ac('forms:track', '#firstFormId, #secondFormId');


Example: Track a webpage with 3 forms

Sample webpage with multiple forms

<!DOCTYPE html>
<html>
  <body>

    <h2>Tracking Forms Example</h2>

<!--Form 1-->
    <h3>Get Name Form</h3>
    <form id="get-name" data-origID="get-name"  data-origID="get-name"  data-origID="get-name"  data-origID="get-name"  data-origID="get-name"  data-origID="get-name"  data-origID="get-name"  data-origID="get-name"  data-origID="get-name"  action="/submit-name">
      First name:<br>
      <input type="text" name="firstname">
      <br>
      Last name:<br>
      <input type="text" name="lastname">
      <br><br>
      <input type="submit" value="Submit">
    </form>

<!--Form 2-->
    <h3>Get Account Information Form</h3>
    <form id="get-account-information" data-origID="get-account-information"  data-origID="get-account-information"  data-origID="get-account-information"  data-origID="get-account-information"  data-origID="get-account-information"  data-origID="get-account-information"  data-origID="get-account-information"  data-origID="get-account-information"  data-origID="get-account-information"  class="target-class" action="/submit-account">
      Account No.:<br>
      <input type="text" name="account">
      <br>
      Account branch:<br>
      <input type="text" name="branch">
      <br><br>
      <input type="submit" value="Submit">
    </form>

<!--Form 3-->
    <h3>Register for Newsletter Form</h3>
    <form id="register-for-newsletter" data-origID="register-for-newsletter"  data-origID="register-for-newsletter"  data-origID="register-for-newsletter"  data-origID="register-for-newsletter"  data-origID="register-for-newsletter"  data-origID="register-for-newsletter"  data-origID="register-for-newsletter"  data-origID="register-for-newsletter"  data-origID="register-for-newsletter"  class="target-class" action="/submit-newsletter">
      First name:<br>
      <input type="text" name="firstname">
      <br>
      Last name:<br>
      <input type="text" name="lastname">
      <br><br>
      Email address:<br>
      <input type="text" name="email">
      <br><br>
      <input type="submit" value="Submit">
    </form>

  </body>
</html>

Track all forms in the HTML page

The following code tracks all of the form tags in the HTML page:

ac('forms:track');

or

ac('forms:track', 'form');

Track by element IDs

The following code tracks only the Get Account Information form:

ac('forms:track', '#get-account-information');

The following code tracks both the Get Account Information Form and Get Name Form:

ac('forms:track', '#get-account-information, #get-name');

Track by element classes

The following code tracks all forms with the target-class class. Both the Get Account Information form and Register for Newsletter form are tracked:

ac('forms:track', '.target-class');

Track by a combination of element IDs and element classes

The following code tracks a form with the get-name ID and all forms with the target-class class. As a result, all forms shown in the sample are tracked.

ac('forms:track', '#get-name, .target-class');


Manage form field data

To manage how form field data is sent with form submission and abandonment events, use the captureFormDataOnAbandon and captureFormDataOnSubmit options with the forms:track method. Set these options to true or false, depending on the result you want to obtain.

For example, to record a form abandonment event, but exclude any form field data, set captureFormDataOnAbandon to false.

ac('forms:track', '.hs-form', {
  captureFormDataOnAbandon: false
});
Important
If you do not set the captureFormDataOnAbandon option, or you set it to anything other than false, the option assumes the value is true, and the recorded form abandonment event will contain serialized form data. This data is subject to custom transformation; sensitive fields are automatically excluded. For more information, see Transform data before sending it and Sensitive form fields that are never tracked.

To capture serialized form data for form submission events, set the captureFormDataOnSubmit option to true.

You can set both options at the same time, as shown in the following example.

ac('forms:track', '.hs-form', {
  captureFormDataOnAbandon: false,
  captureFormDataOnSubmit: false
});


Transform data before sending it

To configure the format of the data that is sent with the form submission and abandonment events, specify a custom transform function in the forms:track options. This function receives an object with the form data; it should return an object with the data to be sent with the form events. You can exclude certain fields, rename fields that are not meaningful, or make any other transformations to the form data before it is sent. The data object is a JSON object of "name-value" pairs, where:

  • "name" is the value of the element's id or name attribute
  • "value" is the visitor's input
ac('forms:track', 'form', {
  transform: function (data) {
    return {
      deliveryOption: data['radioButton_3'],
      acceptedLicense: data['checkbox_license']
    }
  }
});

Sensitive form fields that are never tracked

Important
Passwords, hidden fields, and sensitive fields are never tracked.
To denote sensitive fields, use the following regular expression, after removing non-alphanumeric characters from the field name.
/pass|billing|creditcard|cardnum|^cc|ccnum|exp|seccode|securitycode|securitynum|cvc|cvv|ssn|socialsec|socsec|csc/i.


If we track a field that you consider to be sensitive, please contact customercare@genesys.com.