Custom events

Automatic events cover page views, forms and contact links. A successful lead, a sign-up, a click on a key button or a purchase is something your site marks up itself, with one line of JavaScript.

The call

gauss('event', 'callback_request', { placement: 'header', plan: 'pro' });

• the first argument is always 'event'; the tracker doesn't support other commands yet;
• the second is the event name;
• the third is an optional parameters object.

The event is sent right away, along with the current page URL.

Queue stub for early calls

The snippet loads with defer, so gauss isn't available immediately. To keep calls made before the script loads, add this stub to the <head> before the snippet:

<script>
  window.gauss = window.gauss || function () { (window.gauss.q = window.gauss.q || []).push(arguments); };
</script>
<script defer data-site="YOUR_SITE_ID" src="https://collect.gausslab.io/js/gauss.js"></script>

The stub queues calls, and once the tracker loads it sends them in order, right after the page_view. With the stub in place, you can call gauss(...) anywhere on the page without checking whether the script has loaded. Without it, a call made before the script loads throws a ReferenceError. If your site uses a Content Security Policy, the inline script needs a nonce or a hash; see Installation.

Naming rules

Event names and parameter keys:

• use only lowercase Latin letters a–z, digits 0–9 and _;
• start with a letter;
• are no longer than 40 characters.

An event name can't start with gauss_, ga_, google_ or firebase_; these prefixes are reserved.

An event with an invalid name isn't sent, and the console shows a [gauss] dropped <name> warning.

Parameters and limits

What happens to anything beyond that:

• parameters past the 25th, keys with invalid names, object values, arrays and NaN are dropped, with [gauss] dropped <key> in the console;
• empty strings, null and undefined are skipped silently;
• items keeps the first 50 entries and drops the rest with a warning;
• the rest of the event is still sent. A markup mistake doesn't break the page: the tracker never throws exceptions into your site's code.

Don't send email addresses, phone numbers, names or other personal details in parameters. How Gauss cleans such values on the server is covered in What data is collected.

Recommended names

For common actions, use names from the GA4 vocabulary. If your site is already tagged for GA4, you don't need to change event or parameter names; see GA4 compatibility.

How to tag purchases, products and conversion value is covered in Conversions and e-commerce.

Examples

A button click:

<button type="button" onclick="gauss('event', 'pricing_click', { placement: 'hero' })">See pricing</button>

A form sent with fetch: form_submit arrives automatically, and generate_lead is sent only after the server responds successfully.

const form = document.querySelector('#callback');
form.addEventListener('submit', async (event) => {
  event.preventDefault();
  const response = await fetch('/api/lead', { method: 'POST', body: new FormData(form) });
  if (response.ok) {
    gauss('event', 'generate_lead', { form_id: 'callback', value: 50, currency: 'USD' });
  }
});

React (with the stub in the <head>, window.gauss always exists):

export function DemoButton() {
  return (
    <button onClick={() => window.gauss?.('event', 'demo_request', { placement: 'pricing' })}>
      Request a demo
    </button>
  );
}

For TypeScript, declare the type once:

declare global {
  interface Window {
    gauss?: (command: 'event', name: string, params?: Record<string, unknown>) => void;
  }
}
export {};

Use debug mode to confirm the event goes out and nothing was dropped.