Breakdance Form Builder Native integration guide

Overview

UTM Grabber automatically writes captured UTMs and click IDs into form fields when the field’s name/ID matches our naming convention. Breakdance’s Form Builder works out‑of‑the‑box—just add hidden fields with the correct IDs.

• Full, authoritative list of supported field names:

Requirements

• WordPress with Breakdance (Form Builder element)
• HANDL UTM Grabber v3+ active and capturing UTMs

---

1) Build your form

• Open your page in Breakdance.
• Add the “Form Builder” element (or edit an existing one).

2) Add hidden UTM fields

For every UTM/click ID you want to store:

1. Add a new Field.
2. Set:
   • Type: Hidden
   • Label: the parameter name (for your reference)
3. Open “Advanced” and set:
   • ID: the exact parameter name (case sensitive)
4. Leave “Value” empty.

Repeat for each parameter you need.

3) Publish the page

4) Test

Visit your form URL with test parameters, submit, and confirm the values in your submission:

https://yoursite.com/contact?utm_source=google&utm_medium=cpc&utm_campaign=bd-test&utm_term=shoes&utm_content=ad1&gclid=123abc

---

Field names to use (IDs must match exactly)

Recommended first

Create these as Hidden fields (ID shown = field ID you must use):

• utm_source
• utm_medium
• utm_campaign
• utm_term
• utm_content

Common optional fields

Add any you need (IDs must match exactly):

• user_agent
• handl_ip
• organic_source_str
• traffic_source
• gclid, gbraid, wbraid, msclkid, fbclid, ttclid
• handl_ref
• handl_url

For additional/advanced names (including first-touch/last-touch variants), see the official list:

---

How the mapping works

• UTM Grabber looks for inputs by name or id that match our parameter names and fills them on page load and when the form appears.
• Works with Hidden, Text, Email, etc. Hidden is recommended to keep forms clean.
• Do not prefill the Value—UTM Grabber will do that.

---

Using the captured values

• Email action: include “All Form Fields” or reference the field IDs in the email template.
• Webhooks/POST/Integrations: hidden fields are submitted like any other field, so your CRM/automation receives the UTMs.

---

Troubleshooting

• Values are empty

  • Test on the live front end (not the builder preview).
  • Confirm the field ID exactly matches a supported name (case sensitive, no extra spaces).
  • Clear any “Value” you typed manually.
  • Visit the page with UTMs in the URL, then submit without navigating away.
  • Temporarily disable or adjust caching/optimization/security plugins that might strip query strings or delay scripts.

• Only some parameters appear

  • Not every click includes every UTM (e.g., utm_term is often missing).
  • Verify the parameter is present in your test URL.

• Forms loaded via modal, AJAX, or late in the page

  • Ensure the form is in the DOM for at least a moment before submit; UTM Grabber listens for DOM changes and then fills fields.

---

Best practices:

• Keep hidden fields together near the bottom of your form for maintenance.
• If you duplicate a field, remove any auto-added suffix so the ID remains exact.
• Map these fields in your CRM so values land in the right properties.
• For multi-step forms, use the same Form Builder instance and include the hidden fields in that form.

That’s it—once the hidden fields exist and their IDs match our naming convention, UTM Grabber will populate them automatically and your Breakdance submissions will include reliable campaign attribution.