Description
Pixelonce – fire-once funnel events for Meta Pixel and Meta’s Conversions API. Not affiliated with or endorsed by Meta.
Multi-step forms often live on one URL: a quote, a finance or insurance application, an enrolment. To most pixel setups, a reload, the back button or a second tab all look like another conversion. One applicant becomes four leads, and your ads optimise toward the wrong people.
Pixelonce lets every event declare how often it may fire — every time, once per page view, once per visit, once per session, once per visitor, or once per thing (a product, plan or vehicle id) — and shows you why an event did not fire.
- Standard and custom events. Lead, Purchase, InitiateCheckout, ViewContent and the rest of Meta’s 18 standard events, each usable as a campaign objective — plus your own custom events (QuoteRequested, DocumentsUploaded…), as many as you need.
- Fire once, on purpose. Per-event “how often” rules, and one rule per step even when every step shares a URL.
- See why. A debug overlay (
?stepcount_debug=1) lists every event and the reason it fired or not. - Server-side copy. Sends each event to Meta’s Conversions API as well, under the same event id, so Meta keeps one copy and still counts events an ad blocker stopped.
- Consent first. Nothing loads before marketing consent. Works with the WP Consent API, IAB TCF v2, Cookiebot, Complianz, CookieYes and Borlabs Cookie, can send Google Consent Mode v2 signals, and honours Global Privacy Control (the browser “do not sell or share” signal several US states require).
- Event parameters. Value, currency, content ids, content type and your own parameters — fixed, or read from the page.
- Background submits. Fire an event only when an AJAX or fetch form submit succeeds, without editing the theme.
- Trigger health. Flags buttons and forms that stopped matching after a theme or form change.
- Setup wizard, starter templates, import and export, and an event log.
Everything above is included, with no limits on events, custom events, pages or pixels.
For developers
?stepcount_debug=1opens the debug overlay (administrators on a live site; anyone on a dry-run staging copy).StepCount.emit('EventName')fires an event set to “When the site signals it”.StepCount.consent({marketing: true})tells the plugin about consent from a tool it does not read itself.- Filters:
stepcount_request,stepcount_config,stepcount_enabled,stepcount_debug_allowed,stepcount_purge_page_caches.
External services
Pixelonce sends data only to the services you configure, and only after the visitor has given consent when a consent tool is active.
Meta Pixel (when you enter a pixel id). The visitor’s browser loads https://connect.facebook.net/en_US/fbevents.js and sends the events you declare to Meta, with the parameters you set and the data Meta’s pixel collects (page URL, browser details, Meta cookies). Meta Terms · Meta Privacy Policy · Meta Business Tools Terms
Meta Conversions API (only when you add a Conversions API access token). Your server sends a copy of each event to https://graph.facebook.com/ with the event name, event id, page URL, the parameters you set, the visitor’s IP address and user agent, and Meta’s _fbp / _fbc cookie values when present. Same terms and policy as above.
The plugin itself does not send anything to its authors: no tracking and no remote updates.
Installation
- Install the plugin and activate it.
- Open Pixelonce → Setup and follow the four steps: your pixel id, a starting template, optionally a Conversions API token, then a test.
- Walk through your funnel with
?stepcount_debug=1added to the URL to see each event fire once.
FAQ
Why did my event not fire?
Open the page with ?stepcount_debug=1 while logged in as an administrator. Every event is listed with the reason it fired or not.
Will I count the same conversion twice with the Conversions API?
No. The browser and the server send the same event id, and Meta keeps one of each pair.
Do I need a cookie banner?
If your visitors are in a region that requires consent for marketing cookies (for example the EU, the UK or Brazil), yes. Pixelonce waits for consent from your consent plugin; it is not a banner itself.
Do I need to edit my theme or form plugin?
No. Events are set up in Pixelonce: by page, by click or submit on a CSS selector, or by a background submit that succeeded.
Can I try it on a staging site first?
Yes. Staging copies run in dry run: everything is evaluated and shown in the debug overlay, and nothing is sent.
Can I use my own event names?
Yes. Pick “Custom event…” and type the name: letters, digits and underscores, starting with a letter, at most 40 characters (Meta’s rule). Custom events are sent with the same fire-once rules and the same server-side copy as standard ones. Meta does not let custom events be campaign objectives; use them for custom conversions and reporting.
I use a page cache. Do I need to clear it after changing settings?
No. Saving any Pixelonce setting clears the page caches of WP Super Cache, W3 Total Cache, LiteSpeed Cache, WP Rocket, WP Fastest Cache, SiteGround Optimizer and Autoptimize, so cached pages pick up the new configuration. Other caches (a CDN, a host’s own cache) may need clearing by hand.
How is the server-side endpoint protected?
The browser posts each server-side copy to an endpoint on your own site. It is public, because visitors are not logged in and pages are often cached, but it only accepts requests from your own pages (same origin) carrying a signed token printed into the page, valid for 7 days; only events and pixels your configuration declares, with consent; and it is rate-limited per visitor. If a page stays in a cache for more than 7 days, its browser events still fire but their server-side copies are refused until the page is refreshed in the cache.
What does the diagnostic file contain?
Your Pixelonce configuration, versions of WordPress, PHP, theme and plugins, consent status, trigger health and recent server-side sends. Never your Conversions API token or anything about your visitors.
Screenshots
Changelog
1.0.1
- Renamed to Pixelonce.
- Custom events: send your own event names alongside Meta’s standard events, with no limit.
- Security hardening: imported configurations are sanitised before they are stored; the server-side endpoints accept only same-origin requests with a signed page token.
- Clears page caches when settings change, so cached pages do not keep an old configuration.
1.0.0
- First public release.






