Custom events

Beyond automatic pageviews, Cosmic Insights tracks any event you fire from your app.

Programmatic

window.cosmicInsights('signup', { plan: 'team' });

The first argument is the event name (max 120 chars). The second is a free-form props object. Anything not in the promotable fields list is stored as JSON on the event row in event_props.

Declarative (zero JS)

Add data-cosmic-event to any element. Optional data-cosmic-prop-* attributes become props. The tracker delegates clicks from document, so dynamically-rendered components work without re-binding.

<button
  data-cosmic-event="cta_click"
  data-cosmic-prop-location="hero"
  data-cosmic-prop-variant="b"
>
  Start free trial
</button>

Kebab-case prop keys are normalized to snake_case, so data-cosmic-prop-revenue-cents="4900" lands as revenue_cents: 4900 and is promoted to a top-level column. Numeric coercion is applied to revenue_cents automatically; other props are sent as strings.

Conversions

Conversions are aggregated per event name in the dashboard's Custom events view. Fire any named event from your app and it shows up automatically:

window.cosmicInsights('subscribe_completed', { plan: 'team' });

The Custom events view counts unique converters and (if you also pass revenue_cents) revenue per event name. Drill into the raw rows from the Events tab.

Revenue

Pass revenue_cents as a number; the snippet automatically tags event_type='revenue' and rolls the value up by source and object.

window.cosmicInsights('order_paid', {
  revenue_cents: 4900,
  currency: 'USD',
});

Object attribution

Send object_id (and optionally object_type) on each page so the dashboard can roll up traffic per Cosmic object:

<meta name="cosmic-context" content='{"object_id":"OBJ_ID","object_type":"posts"}'>

The Insights dashboard uses object_id to populate the per-object analytics in the Content tab and the Performance card on each object detail page.

Promotable fields

These keys, if present in your event props, the cosmic-context meta tag, or the script tag, are promoted to top-level columns and become first-class filters in the dashboard. Anything else stays in the JSON event_props blob.

The snippet warns once per typo per page load if it sees common camelCase mistakes (agentId, userId, objectId, revenueCents, etc.) so you can catch them in the browser console during development.

Limits