Event Pipeline

This page is the developer reference for how a click, page view, or custom call becomes payloads sent to CROForge and (optionally) Google Analytics / Tag Manager. A pipeline is an assembly line: each station adds something, then the package ships. In CROForge the stations are “match metrics,” “attach live experiment/variation,” and “push to each integration.”

Doc ID: dev.events. Audience: developer.

Words used on this page

Word	Everyday meaning	Meaning in CROForge
Pipeline	A sequence of stations a package moves through.	Event name + payload → match metrics → attach liveExp → integration.pushData for each entry in CODE.integrations.
Event	Something that happened (a click, a page load).	Named occurrence with apiName and optional properties. Fired by triggers or by CROFORGE.event(...).
Trigger	The tripwire that notices the happening (a click listener, a page load).	Catalog types: page_view, click, scroll, beforeunload, form_submit (if wired). Each has a listener and notes in the table below.
Impression	Proof a visitor was shown a variation.	Live-mode event after assignment and CSS/JS apply; used so reports know who saw what.
Metric matching	Checking whether this event “counts” for a success definition.	getMatchingMetricsIdOfEvent: metric event apiName equals eventName (case-normalized as implemented) and every condition passes via isConditionTrue.
liveExp	A sticky note: “this event happened while this experiment/variation was live.”	Computed by getExperimentAndLiveVariationIdForMetrics(eventName, payload) and attached as eventPayload.liveExp. Only experiments with a live variation id are included (via experimentIdsByMetrics).
Integration	Another system that should hear the same event.	Each object in CODE.integrations gets pushData(eventName, eventPayload). Defaults include CROForge /e, gtag, and dataLayer.
sendBeacon	Browser API that sends data even while the page is unloading.	How the CROForge beacon URL is typically hit; Image pixel is the fallback.
gtag	Google Analytics 4’s event function.	If enabled at runtime: croforge_* event names.
dataLayer	Google Tag Manager’s event inbox.	If enabled at runtime: push event: "croforge_" + name.
activeTime	How long the tab was actually in front of the user, not just open in the background.	Focus + visibility tracking accumulated for beforeunload payloads.

Screenshot filename

Suggested screenshot filename: event-pipeline.png. Capture a flow from trigger → metric match → liveExp → integrations. Insert the real image from the WordPress Media Library in place of this note.

Client API (product snippets)

Prefer the Events API tab in the product UI for copy-paste snippets. The queue-style pattern below is safe before Smart Code finishes loading: calls sit in an array, then flush when the library is ready. static/init.js also documents window._CROFORGE.event as the internal dispatcher once the library is ready.

window.CROFORGE = window.CROFORGE || [];
CROFORGE.event = CROFORGE.event || function () {
  CROFORGE.push(["event"].concat([].slice.call(arguments)));
};
CROFORGE.event("api_name", { prop: "value" });

Processing steps

When an event is dispatched, Smart Code walks every configured integration with the same enriched payload.

1. For each integration in CODE.integrations:
2. Compute liveExp = getExperimentAndLiveVariationIdForMetrics(eventName, payload)
3. Attach eventPayload.liveExp
4. integration.pushData(eventName, eventPayload)

Matching metrics

getMatchingMetricsIdOfEvent decides which metric definitions this event satisfies:

• Metric’s event apiName equals eventName (case-normalized as implemented)
• Every condition passes via isConditionTrue

Then map metric ids → experiment ids via experimentIdsByMetrics, and include only experiments with a live variation id.

Triggers → events

A trigger is the listener; the event is the named payload that follows. “One-shot” means that trigger id fires at most once per page load.

Trigger type	Listener	Notes
page_view	init live mode	Immediate
click	document click	Tag/class heuristics
scroll	throttled scroll	One-shot per trigger id
beforeunload	unload	Sends active time event
form_submit	(if wired)	Defined in catalog

Active time

Focus + visibility tracking accumulates activeTime for unload payloads. That is how CROForge distinguishes “tab open in the background” from “person actually looking at the page.”

Client custom events

Product how-to for firing your own apiName from site code is documented in Custom events. Use the queue-style API above so calls are not lost before Smart Code boots.

Testing checklist

• page_view fires once on load
• click on CTA produces payload with text/href
• metric conditions match expected clicks only
• liveExp contains correct experiment/variation when Running
• GA4/GTM receive croforge_* events if enabled

Related reading

• Smart Code runtime
• Events overview
• Metrics
• Custom events