Setting Up Custom Event Tracking with UniPixel

UniPixel can track more than just page views and WooCommerce events. If there’s a button, link, form, or any element on your site that you want to track — you can set it up as a custom event and send it to Meta, Google, TikTok, Pinterest, or Microsoft.

This guide walks you through the entire process, including how to find the right selector for the element you want to track.

---

What You Need

• UniPixel installed and at least one platform connected (Pixel ID entered)
• Access to your website’s frontend (to inspect elements)
• A modern browser (Chrome, Firefox, Edge — all work)

---

Step 1: Identify the Element You Want to Track

Before you can track something, you need to tell UniPixel which element to watch. UniPixel uses CSS selectors to identify elements. Don’t worry if that sounds technical — it’s simpler than it sounds.

A CSS selector is just a way to point at something on your page. There are three common types:

Selector Type	What It Looks Like	Example
ID	#something	#signup-button
Class	.something	.cta-button
Attribute	[data-something="value"]	[data-action="subscribe"]

IDs are the most reliable because they’re unique — only one element on the page should have a given ID. Classes can match multiple elements, which is sometimes what you want (track every “Add to Wishlist” button) and sometimes not.

---

Step 2: Find the Selector Using Your Browser’s Inspector

Every browser has a built-in tool that lets you see the code behind any element on your page. Here’s how to use it:

To open the inspector:

1. Go to the page on your site where the element lives
2. Right-click on the element you want to track (the button, link, image, etc.)
3. Click “Inspect” or “Inspect Element”

A panel will open showing the HTML code, with the element you clicked highlighted.

What to look for:

You’ll see something like this:

<button id="get-started" class="btn btn-primary cta-main">Get Started</button>

From this, you can use:

• #get-started — the ID (most reliable, unique on the page)
• .cta-main — one of the classes (may match other elements too)
• button.cta-main — more specific: only <button> elements with that class

Another example:

<a href="/contact" class="nav-link contact-link">Contact Us</a>

• .contact-link — the class
• a.contact-link — more specific: only links with that class

If the element has no ID or useful class:

<button class="btn btn-primary">Download Brochure</button>

If the class is too generic (like btn btn-primary which could match dozens of buttons), you have two options:

Option A: Add an ID yourself (recommended if you can edit the page)

Edit the page in WordPress and add an id attribute to the element. In most page builders (Elementor, WPBakery, Gutenberg), there’s an “Advanced” or “HTML ID” field in the element settings. Set it to something descriptive:

• Elementor: Select the element → Advanced tab → CSS ID field
• Gutenberg: Select the block → Advanced panel → HTML anchor field
• WPBakery: Select the element → Design Options or Extra class name

Then use #your-id-name as your selector in UniPixel.

Option B: Use a more specific selector

If you can’t edit the page, you can combine selectors to be more specific:

• .hero-section .btn-primary — only the primary button inside the hero section
• [href="/contact"] — any link that points to the /contact page
• form.newsletter button — the button inside a form with class “newsletter”

---

Step 3: Test Your Selector Before Saving

Before entering the selector in UniPixel, confirm it matches the right element:

1. Open the Inspector on the page (right-click → Inspect)
2. Click the Console tab at the top of the inspector panel
3. Type: document.querySelectorAll('#your-selector') and press Enter
4. The console will show how many elements matched

If it shows 1 element — perfect. That’s exactly what you want for a specific button.

If it shows multiple elements — your selector matches more than one thing. That might be intentional (tracking all “Add to Wishlist” buttons) or you may need a more specific selector.

If it shows 0 elements — the selector doesn’t match anything. Check for typos, or make sure you’re on the right page.

---

Step 4: Add the Custom Event in UniPixel

1. In WordPress admin, go to UniPixel → [Platform Name] → Events
   • For example: UniPixel → Meta → Events
2. Scroll down to the Custom Events section
3. Click Add Event
4. Fill in the fields:

Field	What to Enter
Element Reference	Your CSS selector — e.g. #get-started or .cta-button
Event Trigger	Choose “On Element Clicked” or “On Element Shown” (see below)
Event Name	What this event will be called in your platform’s dashboard — e.g. GetStartedClick, BrochureDownload, NewsletterSignup
Description	Your own note (not sent to the platform) — e.g. “Homepage hero CTA button”
Send Client-side	Leave ON — fires the event in the visitor’s browser
Send Server-side	Leave ON for Meta, TikTok, and Pinterest. For Google, only enable one (client OR server) to avoid double-counting

5. Click Save All Tracking Settings

---

Trigger Types Explained

On Element Clicked — fires when a visitor clicks the element. Use this for buttons, links, CTAs, download links, form submit buttons.

On Element Shown — fires the first time the element becomes visible on the screen (scrolls into view, or appears after page load). Use this for hero banners, promotional sections, sign-up forms, video embeds — anything where seeing it is the event you care about.

“On Element Shown” fires once per page load. If the visitor scrolls past it and back, it won’t fire again.

---

Client-Side vs Server-Side — Which to Enable

For most platforms, enable both. UniPixel automatically deduplicates — it sends the same event ID to both the browser pixel and the server API, so the platform counts it as one event, not two.

Exception — Google: Google only deduplicates the Purchase event. For all other events (including custom events), enabling both client and server will result in the event being counted twice in GA4. Pick one or the other for Google custom events.

Exception — Microsoft: Microsoft only supports client-side custom events. The server-side toggle is disabled.

---

Tracking the Same Element Across Multiple Platforms

If you want to track the same button click in Meta, TikTok, and Google, you need to add the custom event on each platform’s Events page separately. The CSS selector will be the same — you’re pointing at the same element — but the event name might differ depending on what each platform expects or what makes sense in each dashboard.

---

Event Names — What to Use

The event name is what appears in your platform’s reporting dashboard. Some tips:

• Use descriptive names — HomepageCTAClick is better than Event1
• No spaces — use CamelCase (NewsletterSignup) or underscores (newsletter_signup)
• Platform-specific names — some platforms have predefined event names that unlock special reporting. For example, Meta recognises Lead, Contact, Subscribe. If your event matches one of these, use the platform’s name for better reporting. Otherwise, it will appear as a custom event
• Keep it consistent — if you track the same action across Meta and TikTok, use the same or similar event name so you can compare

---

Troubleshooting

Event not firing:

• Open your browser’s Inspector → Console tab. Look for UniPixel-related messages when you click the element or when it appears on screen
• Verify the selector matches on that specific page (see Step 3)
• Check that the platform is connected and the event is saved (not just added but unsaved)
• Check that consent has been granted if you have consent management enabled

Event firing but not appearing in the platform dashboard:

• Platform dashboards can take 5–30 minutes to update (Meta Events Manager, TikTok Events Manager, GA4 DebugView is fastest)
• Check the UniPixel event log (UniPixel → Home) for server-side responses — a 200 status means the platform received it
• Confirm your Pixel ID and Access Token are correct on the platform’s Setup page

Selector matches the wrong element:

• Use the Console test from Step 3 to check what your selector is actually matching
• Make the selector more specific: add a parent class, use an ID instead of a class, or combine selectors
• When in doubt, add a unique ID to the element (see Step 2, Option A)

“On Element Shown” fires immediately on page load:

• This is correct if the element is visible without scrolling. “Shown” means “visible in the viewport” — if it’s above the fold, it fires as soon as the page renders

---

Quick Reference — Common Examples

What You Want to Track	Suggested Selector	Trigger	Event Name
“Get Started” button with ID	#get-started	Click	GetStartedClick
All “Add to Wishlist” buttons	.add-to-wishlist	Click	AddToWishlist
Contact page link in navigation	a[href="/contact"]	Click	ContactNavClick
Newsletter signup form button	.newsletter-form button	Click	NewsletterSignup
Hero banner (visible on page)	#hero-banner	Shown	HeroBannerViewed
Promotional popup	.promo-modal	Shown	PromoViewed
Download PDF link	a[href$=".pdf"]	Click	PDFDownload