Skip to content

Forms Extension

The forms extension enables events that track form changes and submits on the site. This extension provides ways to see what forms it has detected, parse form elements for their inputs and content, and more.

Note

This plugin only tracks standard web form elements. If you are using non-standard frameworks like Bootstrap that don't follow the standard web form implementation, then you'll have to provide custom tracking.1

See below for details on how to do this.

Warning

Forms can contain sensitive values, like passwords! We do some rudimentary checks for inputs like this, and choose not to track those inputs. Generally speaking, sensitive information should be flagged as type=password on the input element.

Installation

This extension can be enabled through Orbee's Platform. If you are manually controlling installation and setup, you can also fetch the plugin here:

<script async src="https://scripts.orb.ee/js-sdk/latest/forms.js" />

This standalone installation sets up the extension's class on the window object, under window.OaFormsExtension. You can then extend your scope like this:

oa.getScope(YOUR_SCOPE).extend('forms', OaFormsExtension);

Configuration

This extension requires no additional configuration at this time.

Methods

This extension has a variety of available attributes and functions to call.

forms.forms

This is an object of forms the extension is currently tracking; the key is the generated ID for that form instance, and the value is the form element on the web page.

forms.forms = {
    "b92258ec-1b11-4b80-8111-729187e3c9f4": <form element-on-page>,
    ...
}

forms.domWatcher

This is an object that uses a MutationObserver to track changes to your website, and continuously add tracking to new forms. It is on by default; you can disable it with forms.domWatcher.stop();.

If stopped, you can also restart it with forms.domWatcher.watch();.

forms.trackForm(formEl)

This function lets you manually enable tracking of a form on the web page. The DOM watcher automatically calls this method for all forms it detects on your website.

forms.parseForm(formEl)

This function lets you parse a form in the format our extension resolves things like form name, input labels and value, etc. This function returns a proper form class that includes methods like getting all input properties or just their values.

Available methods/properties:

  • form.element: returns the element of the form.
  • form.inputs: returns a map of inputs and their properties (label, element, value, validity).
  • form.name: returns the name of the form.
  • form.valid: returns whether we've detected if the form is valid or not. This returns true if validity is unknown.
  • form.getInputValues(): returns the key/val pairs of the forms' inputs, ignoring all other properties of those inputs.

Advanced

If you want to control when data is sent to Orbee, or if you use atypical web practices that cause our form tracking to not be adequate, you can use the following methods to manually send form changes and submits to Orbee:

trackChange(formEl)

This function will track the change of an input in a form. This does parse and send all inputs of the form in the event.

trackSubmit(formEl)

This will track the submit of a form. This does parse and send all inputs of the form in the event.

Events

The extension generates the following events:

Form Changed

oa.track('form changed', {
    _id: "<form instance id>",
    _name: "formName",
    ...inputKeyValues,
});

Form Submitted

oa.track('form submitted', {
    _id: "<form instance id>",
    _name: "formName",
    ...inputKeyValues,
});

Listening

This extension does not listen for any events in the SDK.

Dependencies

This extension does not depend on any other extensions.


  1. We are currently in the process of providing configuration and adapters to track other form frameworks. Check back here for updates on these developments!