Skip to content
Nebulas Docs

Track where leads come from

A lead is more useful when you know which campaign it came from. With trackingParams, NebulasSurface reads parameters from the page URL and sends them as hidden inputs. The visitor never sees a field for them.

  1. Declare the inputs on the widget in Nebulas Studio: utm_source, utm_medium, utm_campaign, and any others you need. Mark them hidden: true so an agent never makes up a value for them. Bind them into the widget’s data so they’re included in the submission (for example as columns in your leads datatable).

  2. Turn on tracking in your page:

    // Visitor lands on /contact?utm_source=newsletter&utm_campaign=spring
    

    // The five standard keys: utm_source, utm_medium, utm_campaign, utm_term, utm_content
    <NebulasSurface surfaceName="contact_form" trackingParams />
    

    // Or pick the keys yourself, e.g. Google Ads click id and a referral code
    <NebulasSurface
      surfaceName="contact_form"
      trackingParams={["utm_source", "utm_campaign", "gclid", "ref"]}
    />

Rules

Section titled “Rules”
  • Parameters are read once, when the form mounts.
  • Only parameters that are actually in the URL are sent.
  • If you pass the same key in inputs, your inputs value wins.
  • Every key must be declared on the widget. Nebulas rejects inputs it doesn’t know about, and the error names the unknown keys and the declared ones. That’s why tracking is opt-in: a form without utm_* inputs would otherwise break on any URL that carries one.

When the URL isn’t in window.location

Section titled “When the URL isn’t in window.location”

If your router owns the query string, or the visitor landed on another page before reaching the form, pass the parameters yourself with searchParams:

"use client";
import { useSearchParams } from "next/navigation";


const params = useSearchParams();


<NebulasSurface
  surfaceName="contact_form"
  trackingParams
  searchParams={params.toString()}
/>