Building a custom tracking script

This page is for the developer or marketing agency writing the snippet that goes in a form's Custom tracking HTML box. The non-technical side — where that box lives and who can edit it — is in Tracking & analytics.

---

Do you actually need one?

If the tool you are wiring up is Meta Pixel or Google Tag Manager, you almost certainly don't. Both have their own field in the Tracking panel, and InsurGrid loads and fires them for you — Meta gets a PageView on open and a Lead on submission; a GTM container receives all three events below, pushed to the standard window.dataLayer under their insurgrid_ names, ready to hang Custom Event triggers on.

A custom script is for everything else: a call-tracking product, an ad network that isn't Meta, your own analytics endpoint.

If a GTM container is already configured on the form, prefer doing the work inside GTM. A tag triggered on insurgrid_form_completed in your own container is easier to change later than a snippet pasted into the form.

---

What the box accepts

Worth reading before you write anything — these limits shape the snippet:

• <script> tags only, with either a src or inline JavaScript. At least one script is required.

• A src must be HTTPS.

• Allowed script attributes: async, crossorigin, defer, id, integrity, referrerpolicy, src, type. Everything else — including every on* handler — is rejected.

• 10,000 bytes total.

Inline JavaScript is parsed (never executed) and refused if it uses eval, Function, setTimeout, setInterval, atob, document.write, document.writeln, Worker, WebAssembly, with, or debugger. Most vendor snippets pass. A few that self-schedule with setTimeout do not — load those from a src URL instead of inlining them.

Validation happens on save: a rejected snippet fails the whole save with an error naming what was refused, and nothing is partially applied.

Load order is guaranteed. A <script src> with neither async nor defer finishes loading before the next script is added, so a second script can rely on what the first one defined. Scripts marked async or defer get no such guarantee.

<noscript> fallback pixels are not supported. Many vendor snippets come in two halves — a <script> and a <noscript><img></noscript> tracking pixel for visitors without JavaScript. Paste only the <script> half. The <noscript> half will not run, and a pixel there records nothing.

That is not a limitation worth working around: the form is a JavaScript application and does not render at all with JavaScript disabled, so the only situation a <noscript> pixel exists for is one where nobody reaches the form in the first place.

This code runs on a page where consumers type names, addresses and policy details, and it has full access to that page. Only add HTML from a vendor you trust — the validation above is a guardrail, not an audit.

---

The events you can hook into

The form publishes its lifecycle to a plain array at window.insurgridDataLayer. Three events, each at most once per form, per browser session:

Event	Fires when
insurgrid_form_view	The public form page loads.
insurgrid_form_started	The consumer completes the first step and it saves successfully. A step that fails to save does not count as a start.
insurgrid_form_completed	The final step is accepted by the server — a real submission, not an attempt.

Every entry has the same two fields:

{
  "event": "insurgrid_form_completed",
  "form_public_id": "kQ8vN2rT7xLpZ3mWyB6dCa"
}

Only the event name and the form's public ID — the same identifier that appears in the form's public URL, and the same for every visitor of that form. Answers are never published: no names, addresses, or uploaded files. If you need the submission data itself, that is server-to-server — the form-submission webhook or the Submissions API.

On forms that hand the consumer to a carrier login, insurgrid_form_completed fires on the confirmation page they return to, not at the moment they leave.

---

Writing the script

The one thing to get right: an event may already have fired before your script runs. insurgrid_form_view is published in the same tick that installs your snippet, so anything fetched over the network arrives too late to witness it. A listener that only watches for future pushes will silently miss the view event on every single visit.

So do both — replay what is already in the array, then intercept later pushes:

<script>
  (function () {
    var layer = (window.insurgridDataLayer = window.insurgridDataLayer || []);

    function handle(entry) {
      if (!entry || !entry.event) return;

      // Your code here.
      console.log('InsurGrid:', entry.event, entry.form_public_id);
    }

    layer.forEach(handle); // events that already fired

    var push = layer.push; // events still to come
    layer.push = function () {
      var result = push.apply(layer, arguments);
      for (var i = 0; i < arguments.length; i++) handle(arguments[i]);
      return result;
    };
  })();
</script>

That wrapper is the whole pattern. Everything below is what you put inside handle.

When a GTM container is configured, the completion push carries an eventCallback with a 500ms eventTimeout, so the form holds navigation briefly for a tag that acknowledges it. A sendBeacon or an image ping has time to leave the browser; a slow fetch may be cut off by the page change. Don't put a long request on the completion path.

---

A complete example

Two scripts: the vendor's tag, then your wiring. Because the first has a src and no async/defer, it is finished loading before the second is added — so window.exampleTracker exists by then. The guard is there for the case where the vendor's CDN fails, which lets loading continue rather than stalling the chain.

<script src="https://cdn.example.com/tracker.js"></script>
<script>
  (function () {
    var layer = (window.insurgridDataLayer = window.insurgridDataLayer || []);

    function handle(entry) {
      if (!entry || !entry.event) return;
      if (!window.exampleTracker) return; // vendor script failed to load

      if (entry.event === 'insurgrid_form_view') {
        window.exampleTracker.page({ form: entry.form_public_id });
      }

      if (entry.event === 'insurgrid_form_completed') {
        window.exampleTracker.conversion({
          type: 'quote_request',
          form: entry.form_public_id,
        });
      }
    }

    layer.forEach(handle);

    var push = layer.push;
    layer.push = function () {
      var result = push.apply(layer, arguments);
      for (var i = 0; i < arguments.length; i++) handle(arguments[i]);
      return result;
    };
  })();
</script>

Posting a conversion to your own endpoint instead, with no vendor script at all:

<script>
  (function () {
    var layer = (window.insurgridDataLayer = window.insurgridDataLayer || []);

    function handle(entry) {
      if (entry && entry.event === 'insurgrid_form_completed') {
        navigator.sendBeacon(
          'https://analytics.example.com/collect',
          JSON.stringify({ type: 'quote_request', form: entry.form_public_id }),
        );
      }
    }

    layer.forEach(handle);

    var push = layer.push;
    layer.push = function () {
      var result = push.apply(layer, arguments);
      for (var i = 0; i < arguments.length; i++) handle(arguments[i]);
      return result;
    };
  })();
</script>

Note there is no setTimeout anywhere in either example — it would be rejected on save. If your vendor's snippet retries or defers on a timer, host that logic in the file you load over src rather than inlining it.

---

Testing

1. Publish the form and open its public link with the browser console open.

2. Inspect window.insurgridDataLayer — it lists what has fired so far.

3. Step through the form and submit it. You should see exactly one entry per event, and your own handler firing on each.

If an event never reaches your handler, the usual cause is the timing problem above: confirm your snippet replays the existing array rather than only wrapping push.

Because events deduplicate per session, a second run in the same window produces nothing. Use a new incognito window for each test pass, not a page refresh.

---

Related

• Tracking & analytics — setting tracking up, and the Meta and GTM fields.

• Webhook events & payloads — the form-submission event, which carries the answers.

• Submissions API — pull submissions on demand.

• Embed a form — putting the form in your own app.