Track Events

X-Ray autocaptures pageviews, clicks, form submits, outbound links, and web vitals. Add explicit tracking for conversion events that should feed campaign reports and ad platform postbacks.

Conversion events

Use the cv constant for type-safe conversion names. Import it from @hellyeah/x-ray in client code or @hellyeah/x-ray/server in server code.

import { cv, track } from "@hellyeah/x-ray";

track(cv.leadSubmit, {
  plan: "pro",
});

track(cv.purchase, {
  revenue: 49.99,
  currency: "USD",
});

cv.purchase sends "cv_purchase", cv.leadSubmit sends "cv_lead_submit", and the typed constants prevent typos that would otherwise break ad platform postbacks.

Server events

Use the server import for webhooks, background jobs, and API routes.

import { XRay, cv } from "@hellyeah/x-ray/server";

const xray = new XRay("your-website-id");

await xray.trackImmediate(cv.purchase, {
  revenue: 49.99,
  currency: "USD",
  distinctId: "user-123",
});

Conversion events appear in campaign reports and help Hellyeah understand what happened after the ad click.

Custom events

Custom events are available for product-specific behavior that is not a conversion. Keep them secondary to typed conversion events.

import { track } from "@hellyeah/x-ray";

track("pricing_viewed", {
  plan: "pro",
});

Naming rules

• Use snake_case
• Keep names stable
• Use cv constants for business outcomes
• Put details in properties instead of creating too many event names