Unified Event Tracking API

Overview

The HagiCode marketing site currently uses 51LA as the analytics provider, but product code must not call LA.track() directly.

All website events must flow through the internal tracking layer under repos/site/src/lib/analytics/ and only the internal 51LA adapter may talk to the third-party SDK. This gives us three benefits:

• Lower coupling: pages and components depend on internal APIs instead of a vendor global.
• Better portability: replacing the analytics vendor only requires adapter-level changes.
• Better governance: event names, entry points, and review rules stay centralized.

API Contract

Code entry points

The core website tracking files are:

• repos/site/src/lib/analytics/events.ts: normalized event registry
• repos/site/src/lib/analytics/provider-51la.ts: the only adapter allowed to call LA.track()
• repos/site/src/lib/analytics/tracker.ts: shared runtime, queue protection, declarative delegation, and trackEvent() API

Imperative usage

React components should use trackEvent() for tracked interactions:

import { WEBSITE_TRACKING_EVENTS } from '@/lib/analytics/events';
import { trackEvent } from '@/lib/analytics/tracker';

trackEvent(WEBSITE_TRACKING_EVENTS.openDesktopPage, {
  source: 'install-options-desktop',
});

Recommended for:

• React button clicks
• Dropdown item selection
• interactions that choose an event name dynamically

Declarative usage

Astro pages should prefer data-track-event and the optional data-track-source for plain links and buttons:

<a
  href={dockerComposeDocsUrl}
  data-track-event="open-container-deployment-guide"
  data-track-source="container-cta-primary"
>
  Go to Deployment Guide
</a>

The shared runtime delegates these events in the browser, so pages do not need to embed direct third-party analytics calls.

Initial Event Catalog

Event name	Trigger location	Business meaning
download-desktop	Primary install button on homepage or navbar	User intends to install/download Desktop
open-desktop-page	Desktop card in the homepage install section	User opens the Desktop product page
open-container-page	Container card in the homepage install section and container fallback links	User opens the Container product page
download-desktop-windows	Windows download actions on Desktop page or install menus	User downloads a Windows package
download-desktop-macos	macOS download actions on Desktop page or install menus	User downloads a macOS package
download-desktop-linux	Linux download actions on Desktop page or install menus	User downloads a Linux package
open-container-deployment-guide	Container deployment guide CTA and FAQ documentation links	User opens container deployment documentation
open-container-source-repo	Container page GitHub CTA	User opens the related source repository

Keep this catalog aligned with repos/site/src/lib/analytics/events.ts. If an event is added, removed, or renamed in code, update the documentation in the same change.

Prohibited Patterns

Avoid the following:

• calling LA.track('...') directly from pages, components, or MDX content
• inventing new event names in random files without registering them centrally
• creating multiple overlapping names for the same user intent
• letting analytics failures block downloads, navigation, or page rendering

Naming Rules

Use kebab-case and follow these guidelines:

• name the user intent first, then the target, for example open-desktop-page
• for download events, distinguish by platform, for example download-desktop-windows
• keep names stable and avoid putting copy, styling, or experiment labels into the event itself
• when only the source differs, prefer data-track-source or context metadata instead of a brand-new event name

Extension Checklist

When adding, renaming, or extending a tracked event, follow this order:

1. update the normalized registry in repos/site/src/lib/analytics/events.ts
2. decide whether the interaction should use imperative trackEvent() or declarative data-track-event
3. wire the tracked UI through the shared runtime
4. confirm direct vendor calls still live only in provider-51la.ts
5. update this guide’s catalog, examples, and explanations
6. rerun site validation and confirm the interaction still works as expected

Runtime Guarantees

The unified tracking system includes two important protections:

• SDK-not-ready queue: events can be queued briefly until the 51LA SDK becomes available
• graceful no-op fallback: if the SDK never loads, tracked interactions still continue without runtime errors

Analytics should help us observe product behavior, not block the product itself.