Tracking

Provision a tracker and wire X-Ray events into your app so conversions close the loop.

Tracking has two pieces:

hellyeah tracker ... in the CLI provisions and links 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

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

hellyeah tracker list

Link the project

Bind the tracker to the current project so the CLI and installed agent skills can find it without re-prompting:

hellyeah tracker link <trackerId>

Writes ./.hellyeah/config.json and appends .hellyeah/ to .gitignore.

Install the SDK

Once you have a trackerId, install the SDK in your app:

npm i @hellyeah/x-ray

Then drop the script or the framework wrapper. See Install the SDK for snippets for Next.js, Remix, Vue/Nuxt, Svelte, Astro, vanilla HTML, and Node/Bun servers.

Or let your coding agent wire it for you:

hellyeah tracker install

This installs the tracker skill and launches your agent so it can write the snippet into your codebase in the right place.

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.

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

Prompt for your agent

Paste this into your agent to provision a tracker and wire the SDK into the current codebase in one shot:

Wire Hellyeah X-Ray tracking into this project.

1. Detect the framework (Next.js, Remix, Nuxt, Svelte, Astro, plain HTML, or Node/Bun). Tell me what you found.
2. Run `hellyeah tracker create --domain <DETECTED_DOMAIN> --yes` if no tracker is linked yet. Use `hellyeah tracker list` first to check.
3. Run `hellyeah tracker link <trackerId>` so the project knows its websiteId.
4. Install `@hellyeah/x-ray` with the right package manager.
5. Drop the SDK snippet into the framework's correct entry point (root layout, _app, plugin, etc.). Show me the diff before writing.
6. Identify one obvious conversion (signup, purchase, lead form) and instrument it with `track(cv.<name>, { ... })`. Import `cv` from `@hellyeah/x-ray` on the client or `@hellyeah/x-ray/server` on the server. Show me the diff before writing.

Do not commit. Stop after the diffs are applied so I can review.