Custom events: names, properties and three ways to send them

A pageview tells you which page someone saw. A completed sign-up, a click on "Add to cart", a finished video — those need events. Once recorded, events show up in the events report with counts and people, and you can build goals, funnels and retention on them.

Pick the name before writing code

Don't rename an event once it's in use: the name is the key in your data, and renaming splits old and new data into two lines. The display name can change any time in the console.

Naming rules:

• Lowercase letters and underscores (snake case), starting with a letter, up to 40 characters: sign_up, add_to_cart, video_complete.
• No $, _ or tc_ prefix. $ is reserved for preset app and mini-program events; double underscores for events the website script records on its own.
• Use the same name for the same action on web, app and mini program, so cross-platform reports can combine them.

Not sure about a name? Try the event naming checker.

Option 1: call it from the page

Once the script has loaded, the page has an analytics object with a track method: the event name first, a properties object second. A copy-ready snippet is in the console under Website analytics › Configuration › SDK code › Custom events.

If the event happens before the script has run — on page load, say — push it into the queue instead; the script sends it when it starts:

<script>
  window.__tcq = window.__tcq || [];
  window.__tcq.push(['track', 'pricing_view', { plan: 'pro' }]);
</script>
<script defer src="https://static.pathclue.com/client.js" data-site="YOUR_SITE_KEY"></script>

Property limits

• Up to 20 properties per event.
• Property names are cut at 50 characters, string values at 200.
• Only strings, numbers and booleans. Objects and arrays are dropped.
• Limits are applied by silent truncation — the event is still sent, never dropped because one value was too long.

Only add properties you will actually split by: plan, product category, button position. Don't put free-text user input in them; you can't analyse it and it may carry personal data. By default, strings that look like email addresses or phone numbers are replaced with a placeholder before storage.

Option 2: no code, define afterwards

On Pro and above you can switch on autocapture. The script then records clicks on clickable elements (password fields, areas marked data-tc-ignore and the chat window are skipped). Those clicks don't become events directly. They land in Product analytics › Data management › Event inbox, where you accept them, name them or merge them into an existing event. Accepting creates a rule and backfills the last 90 days.

Good fit: many buttons, frequent redesigns, little engineering time. Poor fit: amounts, order numbers and anything else that has to be exact.

More in Autocapture and the event inbox.

Option 3: send from your server

Order values, refunds and renewals are more reliable from the server: ad blockers can't stop them and a closed tab doesn't lose them. See Server-side events API.

A pattern that works well: the front end records "clicked Place order", the server records "payment succeeded" with the amount. Two different names, and the funnel shows how many were lost in between.

Check that it arrived

Trigger the event once, then look at Website analytics › Real-time or Website analytics › Events. Identical events — same visitor, same page, same name and properties within one second — are de-duplicated, so a burst of test clicks counting once is expected.