Custom Events, Web Vitals & Privacy APIs

Beyond pageviews, diy-analytics gives you a client-side API for tracking custom actions — signups, purchases, clicks — plus automatic Core Web Vitals monitoring and privacy consent controls.

Tracking custom events

Call window.trackEvent(name, data) anywhere in your client code, once the tracker has loaded:

javascript

window.trackEvent('plan_upgraded', {
  plan: 'pro',
  billing: 'annual',
  seats: 5
});

Parameters

name (string, required) — a descriptive identifier for the event (e.g. signup_completed, checkout_started, video_played). Max 64 characters.
data (object, optional) — a flat key-value object of metadata. Values must be scalar: string, number, or boolean.

Keep event payloads flat. Scalar values are extracted and aggregated automatically for breakdown charts in your dashboard. Payloads over 8 KB are sanitized and truncated on ingestion.

TypeScript definitions

For full type safety in a Next.js or TypeScript frontend, add this ambient declaration to globals.d.ts or types/analytics.d.ts:

typescript

// types/analytics.d.ts
declare global {
  interface Window {
    trackEvent?: (
      name: string,
      data?: Record<string, string | number | boolean | null>
    ) => void;
    optOutAnalytics?: () => void;
    optInAnalytics?: () => void;
    isOptedOut?: () => boolean;
  }
}

export {};

Tracking recipes

1. SaaS onboarding & activation

typescript

// Track user signup
window.trackEvent?.('user_registered', {
  method: 'github',
  referral_campaign: 'spring2026'
});

// Track feature activation
window.trackEvent?.('report_exported', {
  format: 'csv',
  row_count: 500
});

2. E-commerce & checkout

typescript

// Add product to cart
window.trackEvent?.('cart_item_added', {
  product_id: 'prod_102',
  category: 'footwear',
  price: 89.99
});

// Completed order
window.trackEvent?.('order_completed', {
  order_id: 'ord_9841',
  total_amount: 179.98,
  coupon_applied: true
});

3. Media & content engagement

typescript

window.trackEvent?.('video_milestone_reached', {
  video_id: 'intro_walkthrough',
  percentage: 75
});

Event names starting with a double underscore (__cls, __lcp, __inp) are reserved for internal metric telemetry. Don't prefix custom events with __.

Automatic Core Web Vitals

The tracker listens to browser performance metrics via the PerformanceObserver API, with no external dependencies.

Metric	What it measures	Good	Needs improvement	Poor
LCP (Largest Contentful Paint)	Loading speed and perceived performance	≤ 2.5s	2.5s – 4.0s	> 4.0s
CLS (Cumulative Layout Shift)	Visual stability and unexpected layout jumps	≤ 0.1	0.1 – 0.25	> 0.25
INP (Interaction to Next Paint)	UI responsiveness and interaction latency	≤ 200ms	200ms – 500ms	> 500ms

Vitals are aggregated and reported at the 75th percentile (P75) on your project dashboard, under Web Vitals.

Visitor opt-out & privacy APIs

If you run a custom cookie or privacy preferences modal, diy-analytics gives you methods to respect visitor choices:

javascript

// Disable tracking for this visitor (clears local session storage)
window.optOutAnalytics();

// Re-enable tracking if the visitor gives consent
window.optInAnalytics();

// Check current opt-out status (returns boolean)
if (window.isOptedOut()) {
  console.log('Visitor has disabled analytics.');
}

When a visitor is opted out:

All pageview beacons are suppressed.
window.trackEvent() calls become safe no-ops.
Web Vitals performance observers are disconnected.

Next steps

Error & Crash Monitoring

Capture uncaught JavaScript exceptions, stack traces, and breadcrumbs.

Funnels & Retention

Construct multi-step conversion funnels and weekly cohort matrices.

Goals & Alerts

Set up conversion targets and trigger automated Slack/Discord webhooks.