Troubleshooting Form Tracking

This guide helps you diagnose and fix common form tracking issues in Usermaven.

---

Forms not being captured

Check if form tracking is enabled

Form tracking is disabled by default. Verify it's enabled in your configuration:

<!-- Check for data-form-tracking attribute -->
<script
  src="https://cdn.usermaven.com/sdk/v1/lib.js"
  data-key="YOUR_API_KEY"
  data-form-tracking="all"  <!-- Should be "all" or "tagged" -->
></script>

Or in JavaScript initialization:

const usermaven = usermavenClient({
  key: 'YOUR_API_KEY',
  formTracking: 'all'  // Should be 'all', 'tagged', or true
});

Using tagged mode but missing attribute

If you're using formTracking: 'tagged', ensure your forms have the data-um-form attribute:

<!-- This form will be tracked -->
<form data-um-form action="/submit">
  ...
</form>

<!-- This form will NOT be tracked (missing data-um-form) -->
<form action="/submit">
  ...
</form>

AJAX forms not detected

Automatic form tracking listens for the standard form submit event. If your form uses AJAX and prevents the default submission, the event may not be captured.

Solution: Use manual form tracking:

document.getElementById('ajax-form').addEventListener('submit', async function(e) {
  e.preventDefault();

  const formData = new FormData(this);

  // Your AJAX submission
  const response = await fetch('/api/submit', {
    method: 'POST',
    body: formData
  });

  if (response.ok) {
    // Manually track the form (use $form to appear in Forms section)
    window.usermaven('track', '$form', {
      form_id: 'ajax-form',
      form_name: 'Contact Form',
      form_action: '/api/submit',
      form_method: 'post',
      fields: [
        { tag: 'input', type: 'email', name: 'email', value: formData.get('email') }
      ]
    });
  }
});

Forms inside iframes

Forms embedded in iframes from different domains cannot be automatically tracked due to browser security restrictions.

Solutions:

• Use thank you page tracking

• Use postMessage to communicate between iframe and parent page

• Track on your server side after receiving the form submission

Shadow DOM forms

Forms inside Shadow DOM (web components) may not be detected by automatic tracking.

Solution: Use manual tracking within your web component:

class MyFormComponent extends HTMLElement {
  connectedCallback() {
    const shadow = this.attachShadow({ mode: 'open' });
    const form = shadow.querySelector('form');

    form.addEventListener('submit', (e) => {
      e.preventDefault();
      const formData = new FormData(form);

      // Track manually (use $form to appear in Forms section)
      window.usermaven('track', '$form', {
        form_id: 'shadow-form',
        form_name: 'Shadow DOM Form',
        form_action: window.location.href,
        form_method: 'post',
        fields: [
          { tag: 'input', type: 'email', name: 'email', value: formData.get('email') }
        ]
      });
    });
  }
}

Single Page Applications (SPAs)

In SPAs, forms may be dynamically added after initial page load. Usermaven should detect these automatically, but if not:

Solution: Ensure Usermaven is initialized before forms are rendered, or use manual tracking.

Forms without <form> element

If your "form" is built with divs and inputs without a <form> wrapper, automatic tracking won't work.

Solution: Either wrap inputs in a <form> element or use manual tracking:

document.getElementById('submit-button').addEventListener('click', function() {
  const email = document.getElementById('email-input').value;

  // Use $form to appear in Forms section
  window.usermaven('track', '$form', {
    form_id: 'div-form',
    form_name: 'Div-based Form',
    form_action: window.location.href,
    form_method: 'post',
    fields: [
      { tag: 'input', type: 'email', name: 'email', value: email }
    ]
  });
});

---

Forms not appearing in dashboard

Recently submitted

Form data may take a few minutes to appear in your dashboard. Wait 2-5 minutes and refresh.

Check browser console for errors

Open your browser's Developer Tools (F12) and check the Console tab for any Usermaven-related errors.

Verify network requests

1. Open Developer Tools > Network tab

2. Filter by "usermaven" or your tracking host

3. Submit the form

4. Look for a request with $form event type

5. Check if the request was successful (200 status)

Ad blockers

Some ad blockers may block tracking requests. Test with ad blockers disabled or use a custom tracking domain.

---

Field values not captured

Field has um-no-capture class

Fields with the um-no-capture class are intentionally excluded:

<!-- This field will NOT be captured -->
<input type="text" name="ssn" class="um-no-capture" />

Remove the class if you want to capture the field.

Password fields

Password field values are never captured for security reasons. This is by design and cannot be changed.

Field outside form element

Ensure the input is inside the <form> element:

<!-- Correct: field inside form -->
<form data-um-form>
  <input type="email" name="email" />  <!-- Will be captured -->
</form>

<!-- Incorrect: field outside form -->
<input type="text" name="name" />  <!-- Won't be captured -->
<form data-um-form>
  ...
</form>

Field missing name attribute

Fields without a name attribute may not be properly identified:

<!-- Has name attribute - properly captured -->
<input type="email" name="user_email" />

<!-- Missing name attribute - may cause issues -->
<input type="email" id="email" />

Dynamic/JavaScript-populated fields

Fields populated by JavaScript after page load should still be captured if they have values when the form is submitted. If not, ensure the value is set before the submit event fires.

---

Debugging tools

Console logging

Add temporary logging to verify form submissions:

document.querySelectorAll('form').forEach(form => {
  form.addEventListener('submit', function(e) {
    console.log('Form submitted:', this.id);
    console.log('Form data:', new FormData(this));
  });
});

Test with a simple form

Create a minimal test form to isolate the issue:

<form data-um-form id="test-form" action="#" method="post">
  <input type="email" name="email" value="test@example.com" />
  <button type="submit">Test Submit</button>
</form>

<script>
  document.getElementById('test-form').addEventListener('submit', function(e) {
    e.preventDefault();
    console.log('Test form submitted');
    alert('Check your Usermaven dashboard in a few minutes');
  });
</script>

Check Usermaven initialization

Verify Usermaven is properly loaded:

console.log('Usermaven loaded:', typeof window.usermaven !== 'undefined');

---

Common issues and solutions

Issue	Likely Cause	Solution
No forms captured	Form tracking disabled	Add data-form-tracking="all"
Specific form not captured	Using tagged mode	Add data-um-form attribute
AJAX form not captured	Non-standard submission	Use manual tracking
iframe form not captured	Cross-origin restriction	Use thank you page tracking
Field values missing	um-no-capture class	Remove the class
Password not captured	Security feature	By design, cannot change
Delayed dashboard updates	Normal sync delay	Wait 2-5 minutes
Requests blocked	Ad blocker	Disable or use custom domain

---

When to use manual tracking

If automatic form tracking isn't working for your use case, consider switching to manual form tracking. Manual tracking gives you full control and works with:

• AJAX forms

• iframe forms

• Shadow DOM forms

• Custom form implementations

• Forms without <form> elements

• Complex multi-step forms

---

Still having issues?

If you've tried the solutions above and forms still aren't being tracked:

1. Check the Testing & debugging Usermaven installation guide

2. Verify your Usermaven script is loading correctly

3. Test on a different browser or in incognito mode

4. Contact Usermaven support with:

   • Your website URL

   • Browser console logs

   • Network request screenshots

   • Steps to reproduce the issue