Using Clarity Custom Events to Track Specific User Actions Without Hurting Performance

Problem: You need to know when users click a specific CTA

Standard page‑view analytics tell you that a visitor landed on a page, but they don’t reveal whether the visitor interacted with a particular button, form field, or banner. Relying on guesswork or adding heavyweight tracking libraries can slow the page and clutter your data.

Thesis: Clarity’s lightweight clarity('track', …) API lets you instrument any user action with negligible overhead, while staying within the service’s limits.

How the API works

The call is exposed as clarity('track', eventName, properties) where:

• eventName is a string that identifies the action (e.g., 'cta_click').
• properties is an optional JSON‑serializable object with extra context.

The call does not block rendering; it queues the event and sends it with the next periodic beacon (every few seconds).

Worked example: tracking a green “Sign up” button

1. Ensure the Clarity snippet is loaded asynchronously on the page (the default setup).
2. Add a button with an inline handler (you could also attach the listener in a script).
3. Example markup:

<button onclick="clarity('track', 'cta_click', {buttonId: 'signup', variant: 'green'});"
        style="padding:0.5rem 1rem;background:#4caf50;color:white;border:none;cursor:pointer"
        >Sign up</button>

Where to run: the snippet must already be present in the page; no additional permissions are required beyond the ability to edit the page’s HTML or JavaScript.

Verifying the event

1. Open the page in a browser, open DevTools → Network tab.
2. Click the button.
3. Look for a POST request to https://www.clarity.ms/event. In the request payload you should see "eventName":"cta_click" and the properties object.
4. In Clarity’s UI, navigate to the Events tab; after up to 30 seconds the event cta_click appears with the attached properties.

To confirm negligible performance impact, run a Lighthouse audit before and after adding the call; the First Contentful Paint and Time to Interactive scores should stay within normal variance.

Trade‑off and limitation

Clarity enforces a per‑project ceiling of 500 distinct custom event names and a maximum of 100 KB of property data per event. If you fire a unique event for every mouse move or generate high‑cardinality values (e.g., timestamps), you will quickly hit these limits and Clarity may start sampling, reducing data granularity.

Practical way to stay within limits

• Define a fixed set of event names up front (e.g., 'form_start', 'form_submit', 'cta_click').
• Keep properties small: only include IDs or short strings, avoid large blobs or PII.
• Periodically review the Events explorer to see how many distinct names you have used.

Actionable closing

Start by instrumenting the highest‑value user actions—CTA clicks, form submissions, or modal opens—using the clarity('track') call. Verify each event appears in the Network tab and the Clarity UI, then monitor the distinct‑event count to ensure you stay under the 500‑name limit. This approach gives you richer behavioral insight without sacrificing page performance.