Tracking

Tracking has two pieces:

• hellyeah tracker ... in the CLI provisions a tracker for your domain.
• @hellyeah/x-ray is the browser and server SDK you install in your app to collect pageviews, events, and conversions.

There is no separate X-Ray CLI or X-Ray account. X-Ray is the tracking layer inside Hellyeah: what the CLI provisions and what your app sends events to.

Why tracking

Ad platforms optimize for the events you tell them are valuable. Without conversion data, Google Ads can only guess. Tracking closes the loop: it records pageviews, custom events, and conversion events from your site, then feeds those events back into Hellyeah so your campaign reports show what drove signups, purchases, or whatever else matters to your business.

Create a tracker

A tracker represents one website. Its ID is the websiteId you pass to the SDK.

hellyeah tracker create --domain acme.com --yes

If you do not have a production domain yet, create a pre-launch tracker:

hellyeah tracker create --pre-launch --yes

Pre-launch trackers use an opaque .invalid placeholder and return domainPlaceholder: true. When you launch, update the same tracker instead of creating a new one:

hellyeah tracker update --domain acme.com --yes

Returns a trackerId (also valid as websiteId). If you already have one, inspect it:

hellyeah tracker state

Install the SDK

The recommended way is to let your coding agent do it. Install the tracker skill once, and your agent detects the framework, provisions the tracker, installs @hellyeah/x-ray, and places the snippet in the right entry point:

hellyeah skills add tracker --global --yes

Then ask it to "add Hellyeah tracking to this project." It shows you the diff before writing and stops for your review. More on the agent flow lives on Install the SDK.

Prefer to wire it in by hand? Install the package and copy the snippet for your stack:

npm i @hellyeah/x-ray

See Install the SDK for snippets for Next.js, Remix, Vue/Nuxt, Svelte, Astro, vanilla HTML, and Node/Bun servers.

What tracking captures

A short tour of what flows through tracking once it is live.

Events. Autocapture records pageviews, clicks, form submits, outbound link clicks, and web vitals out of the box. Use track() mainly for conversions and the few product events your team reports on.

Conversions. Import the cv constant from @hellyeah/x-ray on the client or @hellyeah/x-ray/server on the server, then call track(cv.purchase, ...) or track(cv.leadSubmit, ...). The constants send cv_* event names without making you hardcode strings that can drift or break postbacks.

Sessions. Basic pageview and event tracking does not require a cookie banner because X-Ray can resolve visits without setting a personal-data cookie for the default flow.

Attribution. Click IDs (gclid, fbclid, msclkid, ttclid, li_fat_id, twclid, gbraid, wbraid) and utm_* fields are captured on first visit and retained for 90 days. Both first-touch and last-touch attribution models are available on reports.

Identify. Calling identify() connects an anonymous visitor to a known user. Email and phone are hashed before storage. Raw contact details are not stored.

Privacy

X-Ray is designed to keep tracking data limited to attribution and reporting. Default tracking avoids raw contact details, hashes email and phone values passed through identify(), and stores click IDs and UTM parameters only so Hellyeah can connect campaign spend to outcomes.

For GDPR-sensitive sites, add tracking to your privacy notice, disclose the 90-day attribution retention window, and avoid sending personal data in custom event properties. If your consent policy requires analytics opt-in, mount the SDK only after the visitor has consented.

Next

• Install the SDK: framework-specific snippets
• Track events: custom events and conversions
• Identify users: known user identity, hashed PII
• API reference: every X-Ray endpoint, grouped