Custom Events, Web Vitals & Privacy Controls

Beyond basic pageviews, diy-analytics supports tracking custom events (like button clicks, signups, or purchases), automatic Core Web Vitals monitoring, visitor privacy opt-out APIs, and traffic exclusion rules.

Pageviews, Web Vitals, and everything else in Connecting Your Website work automatically once the tracking snippet is installed — nothing here is required. Custom events are an optional, code-based feature for tracking specific actions (like "user clicked Buy"); skip this section if you don't need that level of detail or aren't comfortable adding JavaScript to your site.

Custom Events

Call window.trackEvent(name, data) from anywhere in your client-side JavaScript after the tracking script has loaded:

window.trackEvent('signup_completed', { plan: 'pro' });

Parameters

name — A short string identifying the event (e.g., checkout_started, video_played).
data — (Optional) A plain object (serialized to JSON) or primitive value providing event metadata.

Keep payload objects flat and small. Property values are limited to scalar values useful for breakdowns (arrays and nested objects are excluded from dashboard property drill-downs). Payloads over 8 KB are replaced server-side with a truncation marker.

Property Drill-down in Dashboard

Custom events appear in the Top Events panel on your project dashboard. Clicking an event opens a detailed breakdown showing:

Distinct property keys observed for that event.
Value distribution and unique-user counts for selected property keys.

For example, tracking window.trackEvent('signup_completed', { plan: 'pro' }) lets you analyze plan choices without pre-configuring custom schemas.

Event names starting with double underscores (__) are reserved for internal system metrics (e.g. Web Vitals). Avoid using the __ prefix for custom event names.

Core Web Vitals

Largest Contentful Paint (LCP), Cumulative Layout Shift (CLS), and Interaction to Next Paint (INP) are collected automatically by the tracking script via the browser's PerformanceObserver API.

Metrics are reported automatically when the page is hidden or unloaded.
No extra setup or code is required.
Results appear under the Web Vitals panel on your dashboard, rated against Google's thresholds:

Metric	Good	Needs Improvement	Poor
LCP	≤ 2.5s	2.5s – 4.0s	> 4.0s
CLS	≤ 0.1	0.1 – 0.25	> 0.25
INP	≤ 200ms	200ms – 500ms	> 500ms

Visitor Opt-Out API

To respect user consent preferences or build a custom privacy control banner, three methods are exposed on window:

// Stop tracking this visitor and clear local session state
window.optOutAnalytics();

// Resume analytics tracking
window.optInAnalytics();

// Check current opt-out status (returns boolean)
const isOptedOut = window.isOptedOut();

When opted out, the tracking script suppresses all pageview beacons, custom events, and Web Vitals reports.

Excluding Traffic

Under Project → Settings → Tracking & Privacy, you can configure server-side exclusion rules:

IP Exclusion: Exclude your own IP address from being recorded.
URL Path Patterns: Exclude specific path patterns (supporting trailing * wildcards, e.g. /admin/* or /internal/*) from ever appearing in analytics.

Public Dashboards

Enable Public Dashboard Access in project settings to share a read-only dashboard link (/public/<projectId>) publicly without granting workspace user credentials.