# Form Analytic Scripts
# General functionality
There are generally three various analytics events attached to each form:
- From error
- Form submission success
- Form abandonment
Additionally, each form that is submitted to Luminate must have the marketing source codes added as hidden parameters. Each time a form field is touched the name of the touched input is updated in the data layer and is recorded in the subsequent event.
# Forms with configured analytics
Form analytics are enabled with main scripts on the following Luminate forms:
- All e-commerce forms
- Donation forms
- Survey forms
- Sign up forms
- Login forms
- TeamRaiser registration forms
- Customized event registration forms
When new forms are created in AEM or other platforms the form validation and/or analytics script must be called on those forms explicitly to enable analytic tracking on those forms.
# How to add analytics to forms
For all the functions described below to work successfully, the two main JavaScript scripts must be present on each page. The first is the analytics scripts stc-analytics-data-layer.js (opens new window) and the second one is the main script file stc-scripts.js (opens new window). Note, links are given to the automatically created a compiled scripts that serve the Luminate test environment.
# Enable form validation & all analytics functions
The easiest way to add all analytics functions to the form that appear directly on the page is to enable from validation by calling validation function enableFormValidation(formSelector, modules, onSuccessCallback, onErrorCallback, onValidateCallback) (opens new window). This will enable form validation, write in the marketing source codes into forms, attach error, submission, abandonment, and last touched field watchers that will fire off an appropriate function at the right time. Please see the function specifications to properly configure validation and post submission actions.
Note: You can't attach $form.on('submit') or $submitButton.on('click') event on a form with validation, please see function specifications on how you can pass a submission callback function as an parameter to ensure that the callback fires after a valid form submission. Also, see Form Validation article for additional instructions.
# Add form information into the data layer
From data can be added into the data layer by calling a function setAnalyticsForm($form, lastFieldName) (opens new window). The values will be set into digitalData.form property.
If the form is not inserted directly on the page the form data can be set into the data layer by calling setFormAnalyticsData(formId, formName) (opens new window) function.
# Form abandonment
The form abandonment analytics are automatically enabled on the form if enableFormValidation() (opens new window) function is called on the form. The form abandonment is called when the page is unloaded, that is on page unload or refresh.
To manually set form abandonment tracking watcher on the form formAbandonmentAnalytics($form); (opens new window) function must be called. This function will add a body unload watcher, the form abandonment will get tracked before the page is unloaded.
To manually trigger form abandonment tracking on the form setFormAbandonment(formId, formName, lastFieldName) (opens new window) function must be called. This function will right away track from abandonment in analytics.
# Disable form abandonment
In some cases, when a user clicks a back button or they are redirected form abandonment should not be tracked as the navigation doesn't take a user out of the normal flow. Form abandonment can be disabled by calling disableFormAbandonmentAnalytics() (opens new window) function. This will prevent the form abandonment event from firing when the page is unloaded.
# Last touched field
When the form validation is enabled with the enableFormValidation() (opens new window) function, the last touched field will be automatically set for that form.
If the form validation is not configured but you would like to track last touched field, call the function setFormLastField($input); (opens new window) each time a field is changed.
For third-party integration use setFormAnalyticsData(formId, formName, lastFieldName) (opens new window) function to update the last touched input.
# How did you hear about us
If the last touched field has a name how-did-you-hear-select the value of the field will be passed into analytics property to be recorded on form submission. This will be recorded as a custom variable in analytics and will appear in digitalData.form.hearaboutus property.
# Marketing source code
For the purpose of accurate tracking of transactions and sources in Luminate and BBIS we write in marketing source codes that are computed and set by analytics script as Luminate source and sub source codes. If the form validation is enabled with enableFormValidation() (opens new window) this will happen automatically.
To manually set marketing source codes, $form.setMarketingSourceCodes(); (opens new window) function must be called on a Luminate page with a form on it. The call to the function should add two new hidden inputs to the form with names s_src & s_sub_src.
For third-party integration the values of s_src & s_sub_src can be retrieved from cookies stc-analytics-source and stc-analytics-sub_source. Cookies.get('stc-analytics-source'); & Cookies.get('stc-analytics-sub_source');
# Form submission
When the form validation is enabled with the enableFormValidation() (opens new window) function, the analytics form submission event will be automatically called when a form is validated and before it is submitted.
To manually trigger form submission event, setFormSubmission(formId, formName, lastFieldName) (opens new window) function must be invoked. It will trigger the analytics form submission event right away.
# Form error
When the form validation is enabled with the enableFormValidation() (opens new window) function, the analytics form error will be automatically called when the validation encounters errors. All standard Luminate form has been configured to properly handle server errors.
To manually trigger a form error event setFormError(formId, formName, lastFieldName, errorMessage, errorType, errorCode = 422) (opens new window) function must be invoked. It will trigger the analytics form error event right away.
# User contributed content
When a user uploads content, once the upload is successful the function setFormUploadSuccess(fileType, fileLocation) (opens new window) should be called.
# Examples
See Form Validation article in the Development section for examples.