This page explains how SmartDingo Form Tracker fills captured tracking data into your form fields: how a mapping works, how to write CSS selectors, how to find them with the page scanner, and how the plugin decides which form each configuration fills.

Note SmartDingo Form Tracker does not create form fields. It fills values into fields that already exist on your form. If you want a hidden utm_source (or similar) field on a lead, add it in your form plugin first, then map to it here.

How a mapping works

A form configuration is a named group of mappings. Each mapping has three parts, edited on SmartDingo Form Tracker → Settings under Form Configurations:

When auto-fill runs, for each mapping the plugin:

1. Looks up the stored value for the tracked field in browser storage. If nothing is stored (field not enabled, or not captured yet), the mapping is skipped.
2. Finds the target element with the CSS selector. If the selector matches nothing, the mapping is skipped.
3. Sets the element’s value, then dispatches a bubbling input event and a bubbling change event.

Those two events matter: many form plugins run validation, conditional logic, or “dirty field” detection only when a real input event fires. Dispatching them makes the programmatic fill behave like a visitor typing into the field.

Note A skipped mapping fails silently — there’s no visible error on the page. Always confirm fills with the Debug overlay (see below) rather than assuming they worked.

Writing CSS selectors

A selector is standard CSS, resolved with querySelector semantics (the first matching element wins per form). Common patterns:

Prefer an ID or name where you can — classes and positional selectors are more likely to change when you edit the form. If a selector is invalid, that single mapping is skipped and the rest still run.

Hiding a field with the Hide option

Tick Hide on a mapping to conceal a visible input you don’t want visitors to see (for example a text field you’re repurposing to carry utm_source). After filling, the plugin walks up from the input to the nearest field wrapper and sets it to display: none. It recognizes these wrappers:

• .wpcf7-form-control-wrap (Contact Form 7), .gfield (Gravity Forms), .wpforms-field (WPForms), .ff-el-group (Fluent Forms), .elementor-field-group (Elementor Pro), .wsf-field-wrapper (WS Form), .frm_form_field (Formidable Forms), .nf-field-container (Ninja Forms)
• Generic fallbacks: .form-group, .form-row, .field-wrapper, and finally the input’s direct parent element.

Warning Hiding is cosmetic (CSS only). The field is still in the DOM and its value is still submitted. If your form already uses a proper hidden input (type="hidden"), you don’t need the Hide option at all — the field is invisible on its own.

Finding selectors with the page scanner

You don’t have to hand-write selectors. The Scan page button reads a real page and lists its form fields for you.

Using the Scan page modal

1. On a form configuration, click Scan page.
2. Type a URL, or start typing a page title and pick it from the search suggestions.
3. Click Scan. The page loads in a hidden background frame and its forms are detected.
4. Choose the detected form and click Import Selected. The plugin creates one mapping row per enabled tracking field and auto-matches a selector wherever it can.

Auto-matching is heuristic: it matches when a field’s name, id, or label contains the parameter name (e.g. a field named utm_source, gclid, or landing-page). Rows it can’t match are left blank for you to fill — either by picking from the scanned-fields dropdown or by choosing Enter manually.

Behind the scenes: ?sdft_scan=1

The modal works by loading the target page with ?sdft_scan=1 appended. In that mode the plugin loads a selector-discovery scanner instead of the normal tracker. It:

• Runs for administrators only (manage_options) — it never loads for regular visitors.
• Waits ~1.5 seconds so JavaScript-rendered forms (Fluent Forms, Gravity Forms, etc.) finish mounting.
• Builds the most stable selector it can for each field, in priority order: ID → name attribute → data-name → class → nth-child path.
• Also reports inputs that sit outside any <form> element, grouped as Fields without <form> wrapper, so builder forms that don’t use a real <form> tag are still discoverable.

One configuration per form (the best-match rule)

All configurations are tried on every page, but each configuration fills exactly one form — its best match. When auto-fill runs, each configuration:

1. Probes all of its selectors and counts how many match inside each form on the page.
2. Claims the unclaimed form with the most matching selectors.
3. Fills only the fields inside that claimed form.

If every form a configuration matches has already been claimed by an earlier configuration, that configuration is skipped for this fill. Forms are identified by their id, data-id, or position on the page.

Note This is why you should create one configuration per form and give each form distinct selectors. If two configurations point at the same selector on the same form, only one wins it — and lead capture attributes the submission to that same winning configuration, so the form name on your leads stays correct. See Capturing leads.

Form-configuration limits

The number of configurations you can save depends on your plan:

The limit is enforced when you save and again when the tracker loads; extra configurations beyond your plan’s limit are dropped. One configuration can still hold many mappings, so a single form with a dozen tracked fields only uses one configuration.

When auto-fill runs

Fills are attempted at three moments, so late-appearing forms are still covered:

• On page load — once the DOM is ready (only if consent is granted).
• On DOM changes — a mutation observer re-runs fills (debounced) when new nodes appear. This catches AJAX-loaded, multi-step, and popup/modal forms that aren’t in the initial HTML.
• After consent is granted — if a consent mode is active, captured data is buffered in memory and only written and filled once consent arrives. See GDPR & consent.

Testing with the Debug overlay

The fastest way to confirm your mappings is the Debug overlay.

1. Go to SmartDingo Form Tracker → Tools and tick Enable debug overlay on frontend, then save.
2. Reload the form page while logged in as an administrator. A panel appears (visible to admins only) showing:
   • Stored Values — every tracking field with its status: OK, EMPTY, PENDING (waiting on consent), or OFF (not enabled).
   • Per-configuration mappings — each selector marked FOUND or NOT FOUND, the match count, and a SKIPPED note if another configuration already claimed the form.

Use it to catch the two most common problems: a selector that shows NOT FOUND (wrong or changed selector) and a field that shows EMPTY (not captured — check it’s enabled and that your test URL carried the parameter).

Warning Turn the Debug overlay off before going live. It only renders for administrators, but production sites should stay clean. See Before you go live.

Next steps

• Supported form plugins
• Visitor & campaign tracking
• Capturing leads
• Before you go live