Creating Custom Events in PixelYourSite

Last updated: May 26, 2026

Overview

You can track almost any type of interaction with your own events. This video shows how to manually configure your events.

A Custom Event in PixelYourSite Pro is your own event — defined by you, fired on the page conditions you choose, and sent to whichever ad and analytics platforms you have configured (Meta, GA4, Google Ads, TikTok, Pinterest, Bing, GTM).

If the built-in WooCommerce, EDD, and lead events don’t cover the thing you need to track — a CTA click, a video view, a scroll milestone, a form interaction inside a particular funnel, a visit pattern across multiple pages — you build a Custom Event for it.

This article is a full walkthrough of the Custom Event editor: every setting, every trigger type, every condition type, and a handful of realistic recipes at the end.

Where to find Custom Events

In your WordPress admin, go to PixelYourSite Pro → Events → Custom Events. The list view shows every event you’ve created, with its status (enabled or paused), trigger summary, and which platforms it fires to.

To create a new one, click Add new event. To edit an existing one, click its title.

The three things every Custom Event can have

Before going field-by-field, it helps to keep the mental model:

Triggers decide when the event fires (a page visit, a click, a form submission, a scroll position, a purchase, …).
Conditions (optional) decide whether it’s allowed to fire on this particular pageview, for this particular visitor (which page they landed on, what device they’re using, what their user role is, …).
Per-platform parameters decide what gets sent to each destination (the event name Meta sees, the action GA4 logs, the value, currency, custom parameters, etc.).

A Custom Event needs at least one Trigger. Conditions and per-platform parameters are optional but unlock most of the power.

General settings

The General card at the top of the editor holds the basics.

Enable Event. Master switch. When off, the event is saved but never fires.

Event Name. Internal name for the event — the title you see in the list, and the key used in the GTM data layer for the custom parameters object. Pick something descriptive (e.g. Pricing CTA Click rather than Event 5); your future self reading reports will thank you. The event name you send to each ad/analytics platform is configured separately in that platform’s card lower down — they don’t have to match.

Fire this event only once in N hours. Optional throttle. Enable it and pick a window (24 hours is typical). PYS will record that the event has fired for the current visitor and skip it on subsequent pageviews until the window expires. The state is stored client-side (cookie/local storage), so it’s per-visitor and per-browser.

Event Triggers

This is the when.

Trigger Logic: OR vs AND

When you add more than one trigger to a single event, the Trigger Logic radio at the top of the Event Triggers card decides how they combine.

OR (default): the event fires when any one of the triggers is satisfied. Use this when you want a single event to cover multiple equivalent surfaces — e.g. “fire the Newsletter Signup event whether the visitor uses the footer form OR the modal form OR the sidebar form.”
AND: the event fires only when all of the triggers are satisfied on the same pageview. Use this for sequenced or high-intent signals — e.g. “fire Deep Engagement only if they reached the pricing page AND scrolled past 50% AND clicked the demo CTA.”

A note for the technically curious: PYS divides triggers internally into “static” (post type, page visit, home page, number of page visits, WC purchase) and “dynamic” (clicks, scrolls, form fields, video views, …). In an AND combination of both kinds, PYS confirms the static conditions server-side at page load, then hands the dynamic triggers to the in-page state machine, which waits for the remaining triggers to be satisfied before firing.

Fire Frequency: Every time vs Once per page

Every time — if a trigger can satisfy more than once on a single pageview (a button can be clicked again, the visitor can scroll back up and down past a threshold), each occurrence fires the event. The default for engagement and click-style events.
Once per page — the event will fire at most once per pageview no matter how many times the trigger satisfies. Combine with Fire this event only once in N hours if you want a session-level cap instead of a pageview-level cap.

Adding a trigger

Click Add trigger to add another row. Pick the trigger type from the Fire event when … dropdown, configure the trigger-specific options that appear next to it, and optionally add a delay (seconds) if you want PYS to wait before firing (useful for view-counting on the home page or letting a heavy page settle before tracking interactions).

The trigger types

PYS Pro ships with 16 built-in trigger types and picks up additional ones automatically from each active form plugin (Contact Form 7, Gravity Forms, WPForms, Fluent Forms, Elementor Forms, Ninja Forms, Formidable, etc. — whichever you have).

Trigger	Use it for
Page visit	One specific URL or a URL pattern. Supports `*` for “any page.”
Home page	The site’s home page only.
Post type	Pages, posts, products, or any registered custom post type.
Number of Page Visits	Fire after N visits to a page (operators: `=`, `>=`, `<=`, `>`, `<`). Useful for “fire on the 3rd visit” remarketing audiences.
WooCommerce add to cart	Any add-to-cart action in the WC store.
WooCommerce purchase	The thank-you page after a Woo purchase. Has a per-order dedup option (“only fire once per transaction”).
Click on HTML link	Click on an `<a>` whose href matches a pattern. Best for tracking outbound links, downloads, mailto:, tel: links.
Click on CSS selector	Click on any element matching a CSS selector you provide (`.pricing-cta`, `#book-demo`, `button[data-action=signup]`, …). The most flexible click trigger — and the only one with the number of clicks required and time limit between clicks options described just below.
Mouse over CSS selector	Hover (not click) on a CSS selector. Use sparingly — hover is noisier than click.
Page Scroll	Visitor scrolls past a depth threshold (percent of page height).
Embedded Video View	A YouTube or Vimeo embedded video reaches a playback percentage you set.
Embedded Video speed	Fires when a viewer changes the playback speed of an embedded video — see the dedicated section below for the speed change type options and the video-scanning workflow.
Email Link	Clicks on a `mailto:` link.
Copy element (text copy)	Fires when a visitor copies text from an element matching the CSS selector you provide. Great for tracking when visitors are grabbing your phone number, voucher code, address, or any other piece of copyable content.
Filling out a form field	A visitor fills out a specific field of a specific form (useful for form-abandon retargeting — they engaged but didn’t submit).
Google Ads Phone Conversion	Click on a phone number link on pages matched by your URL pattern. See the dedicated Google Ads Phone Conversion doc for the matching Google Ads configuration.
Form plugin	One row per active form plugin. Lets you target one or several forms by ID and fire when a submission completes.

Click on CSS selector — Number of clicks and time limit

The Click on CSS selector trigger has two extra options below the selector list that let you require multiple clicks within a time window before firing.

Number of clicks required. Default 1 (any single click fires). Set to 2 for double-click detection, 3 for triple-click, or higher numbers to track rage-clicking on broken UI. Minimum is 1.
Time limit between clicks (ms, 0 = no limit). The window during which the required number of clicks must happen, in milliseconds. Default 0 (no limit — any N clicks across the whole session count). A value of 500 ms is a tight double-click; 2000 ms is a slow double-tap; 3000 ms is a relaxed triple-click. Set to 0 to disable the time constraint entirely.

A few practical recipes:

Double-click on a CTA — clicks 2, limit 500 ms. Catches users who instinctively double-click buttons.
Rage-click on a broken element — clicks 5, limit 2000 ms. Fires a UX Issue signal you can surface to your product team.
Engagement on a numeric stepper — clicks 3, limit 0. Fires once the visitor has interacted with the control at least three times during the session.

Embedded Video speed

The Embedded Video speed trigger fires when a viewer changes the playback rate of an embedded YouTube or Vimeo video. Setup is a three-step flow:

Enter video pages URL. Pick one or more URL patterns for the pages your embedded videos live on, then click Scan video — PYS visits those pages and detects every embedded video on them.
Select videos. Pick which of the detected videos this trigger should listen on.
Speed change type. Choose what kind of change fires the event:
- Increase speed — only when the viewer speeds the video up (e.g. 1× → 1.5×).
- Decrease speed — only when they slow it down (e.g. 1× → 0.75×).
- Any speed change (default) — both directions.

Common use: an Engaged Viewer signal when somebody speeds up a long-form video — strong evidence they’re committed enough to want it faster — used for retargeting audiences or as a key event in GA4.

Delay

The with delay N seconds input on each trigger pushes the fire moment by N seconds after the trigger is satisfied. Common use: delay a “page view counts as engagement” trigger by 5–10 seconds so it doesn’t fire for bounces. Set to 0 for immediate.

Conditions (optional)

This is the whether.

Conditions are evaluated before triggers and decide whether the event is allowed to fire on this particular pageview, for this particular visitor. They’re how you turn a broad event (“any add-to-cart”) into a targeted one (“any add-to-cart from a visitor who arrived from a Facebook ad”).

Enable Conditions

Toggle the Enable Conditions switch to turn the block on. With the switch off, conditions are ignored entirely.

Logic: AND vs OR

The Logic radio at the top of the Conditions card controls how multiple conditions combine.

AND — every condition must pass before any trigger is even evaluated. Use this when you want to narrow the audience. “Logged-in users AND on Desktop AND landed from a paid campaign.”
OR — if any one condition matches, the event is allowed to fire. There’s a subtle but useful behaviour here: in OR mode, when any condition matches, every non-purchase trigger is automatically marked as ready. The practical effect is that OR turns Conditions into an “any-of” matcher across both the Conditions and the Triggers — useful for casting a broad net like “fire on any of: this landing URL, this user role, this device.”

When in doubt, use AND. It’s the more common case and the more predictable behaviour.

The six condition types

Type	What it compares	Operators
URL filters	The URL of the current page	URL contains, URL match
URL parameters	The query string on the current URL	URL parameters contains, URL parameters match
Landing page	The first URL the visitor landed on in this session	Landing page contains, Landing page match, Landing page URL parameters contains, Landing page URL parameters match
Source	The traffic source / referrer URL captured at the start of the session	Source contains, Source match
Device	Mobile vs desktop (uses WordPress’s `wp_is_mobile()`)	Desktop or Mobile (radio)
User role	The current user’s WordPress role(s), plus a “Guest” option for visitors who aren’t logged in	Multi-select

A few notes:

contains does a substring match — pricing matches https://yoursite.com/pricing/lifetime/.
match is exact-equals.
For URL-style conditions, the comparison is case-insensitive and works with full URLs or path patterns.
You can add as many condition rows as you need, in any combination of types.

Click Add another Condition to add a row, then pick the type from the Select the condition type dropdown.

The Landing page condition

This is the one most people are looking for and the one the previous version of this article didn’t cover well.

When a visitor first lands on your site, PixelYourSite stores the URL they arrived on in a session value (LandingPage) and a cookie (pys_landing_page). The Landing page condition reads that value at the moment the event evaluates — so you’re matching against where the visitor first came in, not where they currently are.

That’s why it pairs so well with attribution use cases that the standard “URL filters” can’t solve:

Attribute conversions to a specific ad campaign. Set a condition with type Landing page, rule Landing page URL parameters contains, value utm_source=facebook. The event will fire only for visitors whose landing URL carried that UTM, even if they’ve since clicked through to ten other pages.
Attribute to a referring blog post. Type Landing page, rule Landing page contains, value /blog/best-tools-for-marketers/. Fires for the conversion no matter where on the site the conversion ultimately happens.
Exclude internal traffic. Combine the Landing page condition with AND logic to require visitors arrived on a specific entry page (e.g. only campaign landing pages, not the WP admin login).

The four landing-page operators break into two flavours:

Landing page contains / Landing page match — compare the landing URL with its query string stripped. Use these to match the path the visitor entered on.
Landing page URL parameters contains / Landing page URL parameters match — compare the full landing URL, query string included. Use these to match UTMs, gclid, fbclid, affiliate IDs, or any other tracking parameter the campaign delivered the visitor with.

The Source condition

The Source condition compares against the traffic source/referrer that PYS captured at the start of the visitor’s session (stored in TrafficSource / cookie pysTrafficSource).

Use it to segment by referring domain:

Source contains facebook.com — fire only for visitors who arrived from Facebook (organic + paid).
Source contains google.com — Google referrers.
Source contains mail. — visitors arriving via webmail clients (common for newsletter tracking when UTMs are absent).

Source is captured once per session and not overwritten by internal navigation, so the value persists through the visit even as the visitor moves between pages.

Device and User role

Device is a hard split: pick Desktop or Mobile. PYS uses WordPress’s built-in mobile detection.

User role is a multi-select of every role registered in your WordPress, plus a built-in Guest option that matches visitors who aren’t logged in. Tick all the roles that should be allowed to fire the event. Typical recipes:

Guest only — fire conversion events only for not-yet-logged-in visitors.
Customer + subscriber — fire engagement events only for paying users.
Administrator excluded — don’t trigger your own ad events when you’re QAing the site (combine with AND on the inverse).

Per-platform parameters

Below Conditions, each connected platform (Meta, GA4, Google Ads, TikTok, Pinterest, Bing, GTM) gets its own card. Turn on the card with the platform’s master switch in the header, then fill in:

Event type / Event name — the standard event name the platform expects (e.g. Meta Lead, Subscribe, CompleteRegistration, …; GA4 generate_lead, sign_up; Google Ads conversion). Each platform’s dropdown includes its full catalogue plus a Custom option for arbitrary names.
Event ID / Pixel — which of your configured pixels the event should fire to. All pixels sends to every pixel of that type; pick specific ones to scope it.
Standard parameters — value and currency are the most common. Many platforms also accept content_name, content_ids, content_category, predicted_ltv, etc.
Custom parameters — arbitrary key/value pairs. For each parameter you can either type a literal value or check Use dynamic value from page and provide a CSS selector — PYS will read the matched element’s text content (or the input’s value, for form fields) at fire time.

The cards are independent. You can configure Meta and GA4 to use different event names, different values, and different parameters from the same Custom Event — useful when each platform has different naming conventions.

Three worked examples

Example 1 — Lead from a Facebook campaign

Goal: a Lead event that fires only when a visitor who arrived from a Facebook ad submits the Contact Form 7 form on your contact page.

General. Event Name: FB Campaign Lead. Fire once in 24 hours: on.
Triggers. Trigger Logic: OR. One trigger — Filling out a form field with the Contact Form 7 contact form selected (or use the Contact Form 7 plugin trigger if you want submit-based, not field-based, firing).
Conditions. Enable on, Logic: AND.
- Landing page → Landing page URL parameters contains → utm_source=facebook
- User role → Guest (exclude already-known customers)
Meta card. Event type: Lead. Value: 50. Currency: USD.
GA4 card. Event action: generate_lead. Mark as a key event in GA4.

Example 2 — Engaged-visitor signal for desktop home-page traffic

Goal: a custom event that fires once per visitor per 24h when a desktop visitor watches at least 50% of the embedded hero video on the home page.

General. Event Name: Home Hero 50% View. Fire once in 24 hours: on.
Triggers. Trigger Logic: AND.
- Home page
- Embedded Video View — set to 50%
Conditions. Enable on, Logic: AND.
- Device → Desktop
Meta card. Event type: ViewContent. Content name: home-hero-video.
GA4 card. Event action: select_promotion.

Example 3 — High-intent CTA click for logged-in users only

Goal: fire a custom Pricing Demo Intent event when a logged-in customer scrolls past 50% of the pricing page AND clicks the demo CTA.

General. Event Name: Pricing Demo Intent. Fire frequency: Once per page.
Triggers. Trigger Logic: AND.
- Page visit → /pricing/*
- Page Scroll → 50%
- Click on CSS selector → .book-demo-cta
Conditions. Enable on, Logic: AND.
- User role → Customer, Subscriber (exclude Guest and Administrator)
Meta card. Custom event name: PricingDemoIntent. Value: 200. Currency: USD. Add a custom parameter plan_visible with Use dynamic value from page set to .pricing-card.featured .plan-name — captures the highlighted plan at the moment the visitor clicked.

Testing your event

After saving, test before relying on the event for optimization:

Browser-side events (Meta, GA4 via gtag, GTM, TikTok, Pinterest, Bing). Open the page that should trigger the event, open the PixelYourSite Pixel Helper (the browser extension), and watch for your event name in the panel as you satisfy the triggers.
Server-side events (CAPI, GA4 Measurement Protocol). Use Meta Events Manager → Test Events for Meta, GA4 Admin → DebugView for GA4, and the platform’s event log for TikTok / Pinterest. Server-side events do not appear in the Pixel Helper.

If nothing fires, the most common causes are: a condition you forgot is blocking it (turn Conditions off temporarily to confirm), the trigger CSS selector doesn’t match the rendered DOM (right-click the element → Inspect to verify), or the “Fire only once in N hours” throttle is still holding from an earlier test (clear cookies for your site to reset).

What’s not (yet) supported

A few things this editor doesn’t currently do, so you don’t waste time looking for them:

No NOT operator on conditions — phrase exclusions by inverting the included set (e.g. include Desktop rather than “not Mobile”).
The WooCommerce purchase trigger is treated as static and is the only trigger that supports the per-order dedup option. In an OR-mode Conditions evaluation the purchase trigger is intentionally excluded from the auto-mark-ready behaviour, so a purchase trigger always has to actually satisfy on its own.
Tags are organizational only — they don’t drive any firing logic.