Form submissions

Form submissions are the most common way to identify contacts and capture leads on your website. This guide explains the fundamental principles of tracking forms with the Positive User SDK.

Introduction

It is important to understand two core concepts before you begin:

1. No Auto-Tracking: The SDK does not automatically detect or track form submissions. You must write your own JavaScript snippet to "listen" for the form submission and send the data to Positive User.

2. Required Method: We strongly recommend using the UE.pageHit() method (explained below) rather than standard event tracking to ensure data integrity.

Why use UE.pageHit()?

When a contact submits a form (like a Newsletter Signup or Login), they are usually transitioning from an Anonymous Visitor to an Identified Contact. The UE.pageHit() method performs two actions in a single, combined request:

1. Identifies the Contact: It updates the contact's profile with the new email or ID, effectively switching the tracking session to the correct contact.

2. Logs the Event: It records that the form was submitted.

By using this method, you guarantee that the "Form Submitted" event is attached to the correct, identified contact profile.

Implementation

To track a form, you need to add an event listener to your form's HTML element.

Basic Code Example

// 1. Select the form element
var form = document.querySelector('#my-signup-form');

if (form) {
    // 2. Add a listener for the 'submit' event
    form.addEventListener('submit', function(e) {
        
        // 3. Extract data from the input fields
        var emailValue = form.querySelector('input[name="email"]').value;
        var nameValue = form.querySelector('input[name="fullname"]').value;

        // 4. Send to Positive User using UE.pageHit
        if (typeof UE === 'object' && typeof UE.pageHit === 'function') {
            UE.pageHit({
                // Identification Data
                email: emailValue,
                first_name: nameValue,
                
                // Event Data
                event: {
                    event_name: 'form_submitted', 
                    source: 'registration_page'
                }
            });
        }
    });
}

Note on Identification Strategies: For robust form tracking, you should ideally pass a unique user_id alongside the form data to guarantee the submission links to the correct profile. The specific method for obtaining this ID during a submission depends on your system's architecture and will be detailed in the Integration Guide.

Mapping attributes

The SDK does not automatically guess which HTML input corresponds to which Positive User attribute. You must explicitly map them in your JavaScript code.

HTML Input	JS Variable	Positive User Attribute
<input name="email">	emailValue	email (Standard)
<input name="fname">	nameValue	first_name (Standard)
<input name="phone">	phoneValue	phone_number (Standard)
<input name="job">	jobValue	job_title (Custom)

Verification

To confirm your form tracking is working, use your browser's Developer Tools (F12).

1. Check SDK Availability: Before testing, ensure the UE object is loaded. Type this into the Console:

   typeof UE.pageHit
   // Expected Output: 'function'

2. Verify Network Request: Open the Network tab and filter for requests containing chatping. Submit your form and look for a new request to .../user-chatping/.
   • Status: 200 OK indicates success.
   • Payload: Click the request and view the Payload tab. You should see your mapped attributes (email, name) and the event object.