Custom Events

Custom events are happenings you define because the built-in page view, click, scroll, and unload events cannot express them cleanly — a purchase, a signup, a video complete, a “plan upgraded” signal. In everyday language they are business milestones, not generic page activity. In CROForge you create the event in the Events catalog (name, stable apiName, properties), copy the API snippet onto your site, fire it with the CROFORGE.event queue API after the action really succeeded, then build a metric that listens for that event and attach the metric to campaigns.

Words used on this page

Screenshot filename: custom-events.png. Paste this page into the WordPress Code editor, then insert that screenshot from the Media library. Do not use a Markdown image tag.

When to create a custom event

Create one when standard click or page_view cannot describe the outcome without brittle guessing. “Clicked a button whose text is Purchase” is a click metric. “Order actually placed for $150 in India” is a custom purchase (or similar) event with numeric and text properties. Prefer the custom event whenever you need a number (revenue) or a fact that never appears in the DOM.

Create in the app

1. Open Events → create a custom event (display name, stable apiName, optional description).
2. Add properties (name, apiName, data type: text / number / boolean / URL, description).
3. Copy the snippet from the API tab onto your site. It already uses this event’s apiName and property keys.
4. Create a metric in Data Vista that listens for that event, with conditions if needed, and a calculation type (unique visitor, unique session, event count, or value of a numeric property).
5. Attach the metric to campaigns.

The recommended product path is still: Add a source (website) → Define events → Run campaigns. Custom events sit in the middle of that path.

Fire from the site

Use the queue stub, then call CROFORGE.event with the event apiName and a flat payload. Example:

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

CROFORGE.event("purchase_countrywise", {
  amount: 150,
  country: "india"
});

The Events API tab wraps the same pattern in a <script> block and fills property placeholders from the catalog. Prefer that snippet. Runtime may also expose window._CROFORGE.event inside init.js once the library is ready; the queue API is what you should paste on the site.

Best practices

Triggers note

A product-level Triggers builder is not a shipped surface in this frontend. You cannot draw “when form submits, fire purchase” inside the CROForge UI. Event firing is via Smart Code standard listeners and/or CROFORGE.event from your site. Leftover editor state such as campaign-executes is not a client feature.

When the custom event fires, Smart Code still matches Data Vista metrics and attaches [experimentId, variationId] pairs for live experiments — the same runtime path as standard events.

Related reading

• Events overview
• Standard events
• Metrics
• Event pipeline