Events
A custom event counts any action on your site that you care about. You add one with a few lines of code, and this guide gives you the code, or an AI prompt that writes it for you.
What a custom event is
TrueMetriks already tracks the standard events for you, such as PageView, Lead and Purchase. A custom event is everything else: a video watched halfway, a button clicked, a pricing section seen.
You choose the name, and your own code decides when it fires. Once it fires, TrueMetriks counts it and passes it on to your ad platforms.
Only Purchase counts as revenue. Total Revenue and ROAS add up Purchase events only. A custom event can carry a value, but that value stays with the event and is never added to Total Revenue or ROAS. If a sale should count, send it as a Purchase. You can fire your custom event as well; it does not count the money twice.
How it works
You paste one short block of code on your site, below your TrueMetriks tracking code. The block starts with a small helper called tmTrack, then the code for the action you want to count.
When the action happens, the code calls tmTrack("EventName"). The helper waits for the TrueMetriks tracker to be ready, then sends the event once per page.
The Events page in your dashboard shows the same examples and the same code as this guide, so you can copy from either place.
The helper
Every example on this page starts with this helper, inside one <script> block. Copy the whole block, including the <script> and </script> tags. Without them, GoHighLevel and ClickFunnels print the code as text on your page.
<script>
/* TrueMetriks: send a custom event. Waits for the tracker, once per page. */
window.tmTrack = window.tmTrack || function (name, details) {
var sent = (window._tmFiredEvents = window._tmFiredEvents || {});
if (sent[name]) return;
sent[name] = true;
var tries = 0;
(function send() {
if (window.tmFireEvent) window.tmFireEvent(name, details);
else if (window.Shopify && Shopify.analytics && Shopify.analytics.publish)
Shopify.analytics.publish("tm_custom_event", { name: name, details: details || {} });
else if (tries++ < 50) setTimeout(send, 200);
else delete sent[name];
})();
};
</script>
The tracker loads in the background, so right after a page opens it is not ready yet. The helper waits for it for up to 10 seconds, so an event that fires the moment the page loads is not lost.
It also sends each event name once per page. A scroll handler that runs on every tick, or a rule you also pasted as code, cannot count the same event twice.
Where to paste it
Paste the block below your TrueMetriks tracking code, so the tracker is on the page before your code runs. Add it on every page where the action can happen.
GoHighLevel
Open your funnel in GoHighLevel under Sites > Funnels and click the Settings tab. Scroll down to Tracking & scripts and find the Head tracking code field. Paste the block on a new line below the TrueMetriks snippet, click Save, then republish the funnel.
ClickFunnels
In ClickFunnels 2.0, open the funnel, click the gear icon at the top right and find Head Code. In ClickFunnels Classic, open Funnel Settings and find Head Tracking Code. Paste the block below the TrueMetriks snippet and click Save.
WordPress
The TrueMetriks plugin already loads the tracker, so you only add your own block. In a header and footer code plugin (for example WPCode), add a new Footer snippet and paste the block there.
Shopify
Shopify keeps the TrueMetriks code in a Custom Pixel, which runs in a locked sandbox. Your theme code cannot call the tracker directly, so the helper hands the event to Shopify's own event channel and the pixel passes it on.
First make sure your pixel is up to date. If the TrueMetriks pixel code in Settings > Customer events does not contain tm_custom_event, copy it again from Settings > Tracking > Shopify in your dashboard and replace the old one. Pixels installed earlier cannot receive custom events until you do.
Then add the block to your theme. In Shopify Admin, click Online Store under Sales channels in the left sidebar.
On your current theme, click the three dots next to Edit theme, then click Edit code.
In the code editor, open the layout folder and click theme.liquid. Scroll to the bottom of the file and paste the whole block on a new line just above the closing </body> tag. Click Save.
- › assets
- › config
- › layout
- password.liquid
- theme.liquid
- › locales
- › sections
- › snippets
- › templates
300 {%- endif -%} 301 302 <script> 303 /* TrueMetriks: send a custom event. ... */ 304 window.tmTrack = window.tmTrack || function (...) { 305 ... 318 }; 319 320 if (location.pathname.indexOf("/contact") !== -1) { 321 tmTrack("ContactPageViewed"); 322 } 323 </script> 324</body> 325</html>
theme.liquid loads on every page of your store, so one paste covers them all. To fire on one page only, keep a URL check like the one in A page is visited. Shopify's checkout pages do not load theme.liquid, but the pixel already tracks checkouts and purchases.
Custom websites
Paste the block into your page's HTML right after the TrueMetriks <script async src=".../t/s-custom.js"> line, on every page where the event can happen. See Custom install for the full tracker API.
Examples
Each example is a complete block: the helper plus the code for that idea. Copy it as it is, and change the event name, the URL or the text to match your site.
A page is visited
Counts a visit to a checkout, thank-you, upsell or booking page. Change /checkout to part of your page's URL.
<script>
/* TrueMetriks: send a custom event. Waits for the tracker, once per page. */
window.tmTrack = window.tmTrack || function (name, details) {
var sent = (window._tmFiredEvents = window._tmFiredEvents || {});
if (sent[name]) return;
sent[name] = true;
var tries = 0;
(function send() {
if (window.tmFireEvent) window.tmFireEvent(name, details);
else if (window.Shopify && Shopify.analytics && Shopify.analytics.publish)
Shopify.analytics.publish("tm_custom_event", { name: name, details: details || {} });
else if (tries++ < 50) setTimeout(send, 200);
else delete sent[name];
})();
};
if (location.pathname.indexOf("/checkout") !== -1) {
tmTrack("CheckoutViewed");
}
</script>
VSL watched %
Counts how much of your sales video a visitor watches: 25%, 50%, 75% and finished. Each milestone has its own name, so each one fires once. The code below works for an HTML5 <video>.
<script>
/* TrueMetriks: send a custom event. Waits for the tracker, once per page. */
window.tmTrack = window.tmTrack || function (name, details) {
var sent = (window._tmFiredEvents = window._tmFiredEvents || {});
if (sent[name]) return;
sent[name] = true;
var tries = 0;
(function send() {
if (window.tmFireEvent) window.tmFireEvent(name, details);
else if (window.Shopify && Shopify.analytics && Shopify.analytics.publish)
Shopify.analytics.publish("tm_custom_event", { name: name, details: details || {} });
else if (tries++ < 50) setTimeout(send, 200);
else delete sent[name];
})();
};
/* Works for an HTML5 <video>. For YouTube, Vimeo or Wistia, use the AI prompt. */
var video = document.querySelector("video");
if (video) video.addEventListener("timeupdate", function () {
if (!video.duration) return;
var pct = video.currentTime / video.duration * 100;
[25, 50, 75, 100].forEach(function (m) {
if (pct >= m - 0.5) tmTrack("VideoWatched" + m);
});
});
</script>
For a YouTube, Vimeo or Wistia player, use the AI prompt in the next section. The general approach for each one is below.
- YouTube: load the IFrame API, use
onStateChangeto know when the video plays, and pollgetCurrentTime()andgetDuration()while it plays. AI prompt line: "The video is a YouTube embed." - Vimeo: use the Vimeo player library and listen with
player.on("timeupdate", ...). AI prompt line: "The video is a Vimeo embed." - Wistia: use
_wq.push({ id: "_all", onReady: function (v) { v.bind("percentwatchedchanged", ...); } }). AI prompt line: "The video is a Wistia embed."
Scroll depth
Counts a visitor who scrolled 75% of the way down the page.
<script>
/* TrueMetriks: send a custom event. Waits for the tracker, once per page. */
window.tmTrack = window.tmTrack || function (name, details) {
var sent = (window._tmFiredEvents = window._tmFiredEvents || {});
if (sent[name]) return;
sent[name] = true;
var tries = 0;
(function send() {
if (window.tmFireEvent) window.tmFireEvent(name, details);
else if (window.Shopify && Shopify.analytics && Shopify.analytics.publish)
Shopify.analytics.publish("tm_custom_event", { name: name, details: details || {} });
else if (tries++ < 50) setTimeout(send, 200);
else delete sent[name];
})();
};
window.addEventListener("scroll", function () {
var max = document.documentElement.scrollHeight - window.innerHeight;
if (max > 0 && window.scrollY / max * 100 >= 75) tmTrack("Scrolled75");
}, { passive: true });
</script>
Button clicks
Counts a click on the button or link with a given text. Change "Apply now" to the text on your button.
<script>
/* TrueMetriks: send a custom event. Waits for the tracker, once per page. */
window.tmTrack = window.tmTrack || function (name, details) {
var sent = (window._tmFiredEvents = window._tmFiredEvents || {});
if (sent[name]) return;
sent[name] = true;
var tries = 0;
(function send() {
if (window.tmFireEvent) window.tmFireEvent(name, details);
else if (window.Shopify && Shopify.analytics && Shopify.analytics.publish)
Shopify.analytics.publish("tm_custom_event", { name: name, details: details || {} });
else if (tries++ < 50) setTimeout(send, 200);
else delete sent[name];
})();
};
document.addEventListener("click", function (e) {
var btn = e.target.closest("a, button");
if (btn && btn.textContent.trim() === "Apply now") tmTrack("ApplyClicked");
}, true);
</script>
Time on page
Counts a visitor who stayed 60 seconds. Change 60000 to the number of milliseconds you want.
<script>
/* TrueMetriks: send a custom event. Waits for the tracker, once per page. */
window.tmTrack = window.tmTrack || function (name, details) {
var sent = (window._tmFiredEvents = window._tmFiredEvents || {});
if (sent[name]) return;
sent[name] = true;
var tries = 0;
(function send() {
if (window.tmFireEvent) window.tmFireEvent(name, details);
else if (window.Shopify && Shopify.analytics && Shopify.analytics.publish)
Shopify.analytics.publish("tm_custom_event", { name: name, details: details || {} });
else if (tries++ < 50) setTimeout(send, 200);
else delete sent[name];
})();
};
setTimeout(function () {
tmTrack("Engaged60s");
}, 60000);
</script>
Section seen
Counts a visitor who scrolled until a section was half in view. Change #pricing to the id of your section.
<script>
/* TrueMetriks: send a custom event. Waits for the tracker, once per page. */
window.tmTrack = window.tmTrack || function (name, details) {
var sent = (window._tmFiredEvents = window._tmFiredEvents || {});
if (sent[name]) return;
sent[name] = true;
var tries = 0;
(function send() {
if (window.tmFireEvent) window.tmFireEvent(name, details);
else if (window.Shopify && Shopify.analytics && Shopify.analytics.publish)
Shopify.analytics.publish("tm_custom_event", { name: name, details: details || {} });
else if (tries++ < 50) setTimeout(send, 200);
else delete sent[name];
})();
};
var section = document.querySelector("#pricing");
if (section && "IntersectionObserver" in window) {
new IntersectionObserver(function (entries) {
if (entries[0].isIntersecting) tmTrack("PricingViewed");
}, { threshold: 0.5 }).observe(section);
}
</script>
Phone, email, WhatsApp
Counts taps on phone, email and WhatsApp links.
<script>
/* TrueMetriks: send a custom event. Waits for the tracker, once per page. */
window.tmTrack = window.tmTrack || function (name, details) {
var sent = (window._tmFiredEvents = window._tmFiredEvents || {});
if (sent[name]) return;
sent[name] = true;
var tries = 0;
(function send() {
if (window.tmFireEvent) window.tmFireEvent(name, details);
else if (window.Shopify && Shopify.analytics && Shopify.analytics.publish)
Shopify.analytics.publish("tm_custom_event", { name: name, details: details || {} });
else if (tries++ < 50) setTimeout(send, 200);
else delete sent[name];
})();
};
document.addEventListener("click", function (e) {
var a = e.target.closest("a[href]");
if (!a) return;
var href = a.getAttribute("href");
if (href.indexOf("tel:") === 0) tmTrack("PhoneClicked");
else if (href.indexOf("mailto:") === 0) tmTrack("EmailClicked");
else if (href.indexOf("wa.me") !== -1) tmTrack("WhatsAppClicked");
}, true);
</script>
Quiz or form steps
Counts each step of a multi-step quiz or form, so you can see where people drop off. Call quizStep(n) from your quiz when a step is shown, and tmTrack("QuizCompleted") when it ends.
<script>
/* TrueMetriks: send a custom event. Waits for the tracker, once per page. */
window.tmTrack = window.tmTrack || function (name, details) {
var sent = (window._tmFiredEvents = window._tmFiredEvents || {});
if (sent[name]) return;
sent[name] = true;
var tries = 0;
(function send() {
if (window.tmFireEvent) window.tmFireEvent(name, details);
else if (window.Shopify && Shopify.analytics && Shopify.analytics.publish)
Shopify.analytics.publish("tm_custom_event", { name: name, details: details || {} });
else if (tries++ < 50) setTimeout(send, 200);
else delete sent[name];
})();
};
/* Call this from your quiz when a step is shown. */
function quizStep(n) {
tmTrack("QuizStep" + n);
}
/* And when it ends: */
/* tmTrack("QuizCompleted"); */
</script>
More ideas
- File downloads
- Chat widget opens
- Coupon code copies
- A FAQ question opened
- A calculator result shown
For any of these, use the AI prompt below.
Let AI write it
For anything the examples do not cover, ask ChatGPT, Claude or Gemini to write the code. Copy this prompt, replace the goal and the platform in square brackets, and send it.
I use TrueMetriks to track my website. Its tracking script is already installed on my site.
It gives me this JavaScript function: window.tmFireEvent(eventName, details).
YOUR GOAL: [describe what you want to track, for example: fire "VideoWatched50" when a visitor watches half of my sales video]
My site is built with: [GoHighLevel / ClickFunnels / WordPress / Webflow / custom code]
Write one <script> snippet that does this. Rules:
1. Start the snippet with this helper exactly as written, and send every event through tmTrack:
/* TrueMetriks: send a custom event. Waits for the tracker, once per page. */
window.tmTrack = window.tmTrack || function (name, details) {
var sent = (window._tmFiredEvents = window._tmFiredEvents || {});
if (sent[name]) return;
sent[name] = true;
var tries = 0;
(function send() {
if (window.tmFireEvent) window.tmFireEvent(name, details);
else if (window.Shopify && Shopify.analytics && Shopify.analytics.publish)
Shopify.analytics.publish("tm_custom_event", { name: name, details: details || {} });
else if (tries++ < 50) setTimeout(send, 200);
else delete sent[name];
})();
};
2. Use short event names with letters, numbers and underscores only. Never use Lead, Purchase, Schedule, AddToCart, InitiateCheckout, ViewContent or PageView.
3. Each event name fires once per page. If something can happen several times (25%, 50%, 75%), give each one its own name.
4. Never put names, emails or phone numbers in the details.
5. Use plain JavaScript that runs in any browser. No libraries.
6. Tell me exactly where to paste it on my platform: below the TrueMetriks tracking code.
7. Tell me how to check it works: open the page and look for the event under Conversions in TrueMetriks.
Paste the code it gives you where described in Where to paste it. Check that it starts with the helper and ends with </script>.
Naming your events
Use letters, numbers and underscores only, and start with a letter. VideoWatched50 and quiz_completed are good names.
GA4 receives the name in lowercase with spaces turned into underscores, and it only accepts letters, numbers and underscores. A name with a | or a -, such as Elite | 3-month, will not reach GA4.
Never reuse a standard name such as Lead, Purchase, Schedule, AddToCart, InitiateCheckout, ViewContent or PageView for something else.
Keep a name stable once your ads or reports use it. Renaming creates a new, separate event.
To rename an event, change the event name in your tmTrack("...") call. The new name starts as a separate event in TrueMetriks, Facebook, TikTok and GA4, and reports do not merge the old and new names. To send an event to one GA4 property under a different name without changing your code, use a custom event mapping on that GA4 property.
Give each milestone its own name, like VideoWatched25 and VideoWatched50. The helper sends each name once per page.
Where your events show up
In TrueMetriks, open Conversions, click the events dropdown and pick your event under Custom events.
Facebook and TikTok receive it as a custom event under the same name. GA4 receives it in lowercase, so PricingViewed becomes pricingviewed. You can rename it for one property with a custom event mapping on the GA4 property.
Google Ads does not receive custom events. It only counts the standard events.
To control what is sent, open Settings > Tracking and expand a Facebook pixel, TikTok pixel or GA4 property. Your own events switches all of your custom events off for that target, and each event also has its own switch there. See Facebook and TikTok.
Check it works
Open the page where the event should fire and do the action. Wait a few minutes, then open Conversions, click the events dropdown and look under Custom events.
For Facebook, open Test events in Events Manager while you do the action, and look for your event name.
If it does not show up, check that the whole block is pasted, with its <script> and </script> tags, below the TrueMetriks tracking code.
Moving from Events page rules
Until now the Events page let you set up events as rules, without code. Rules are replaced by code, which can track far more.
If your site still has rules, the Events page shows a countdown to the date they stop firing, and a Copy all button. Copy all gives you one block of code with every rule turned into code, with the same event names.
Paste that block below your TrueMetriks tracking code. It is safe to paste early: each event fires once per page, whichever runs first, so nothing is counted twice while a rule is still on.
After the cutoff date the rules stop firing, and the events only fire if the code is on your site.
Frequently asked questions
Do I need to know how to code?
No. Copy an example from this page, or copy the AI prompt into ChatGPT, Claude or Gemini and describe what you want to track. Paste the code it gives you below your TrueMetriks tracking code.
Where did the rules on the Events page go?
They were replaced by code, which can track far more. Sites that still had rules got their rules converted to code on the Events page, with a date after which the old rules stop firing.
How do I rename an event?
Change the name in your tmTrack("...") call. The new name starts as a separate event in TrueMetriks, Facebook, TikTok and GA4, and reports do not merge the old and new names. To send it to one GA4 property under a different name without changing your code, use a custom event mapping on that GA4 property.
Are custom events sent to Google Ads?
No. Google Ads only counts the standard events (Lead, Purchase and so on) as conversions. Custom events go to Facebook, TikTok and GA4.
Can I stop one event from going to Facebook?
Yes. In Settings, Tracking, open the Facebook pixel and use Your own events. You can switch all of them off, or just one. TikTok pixels and GA4 properties have the same switch.