Tracking Custom Events

Beyond automatic page views and Web Vitals, you'll want to understand how user interact with specific parts of your app.

How to Track Events

Once you've set up the AnalyticsProvider, you can call the track function from any Client Component to record an event.

"use client";
import { track } from "@zeitgg/analytics";
 
// We're using shadcn compontents in this example, but you get the point
function TrackedButton() {
  return (
    <Button variant="outline" onClick={() => track("button_clicked")}>
      Get Started
    </Button>
  );
}

That's it! When the button is clicked, an event named "get_started_button_clicked" is sent.

Adding Context with Data

Often you'll want to include more details about the event. Pass a simple object as the second argument to track.

"use client";
import { track } from "@zeitgg/analytics";
 
function SubscribeButton({ subscriptionId, price }) {
  const handleSubscribe = () => {
    // your "subscribe" logic
 
    // track the event with product details
    track("subscribe", {
      subscriptionId: subscriptionId,
      itemPrice: price,
      currenty: "EUR", // Example extra detail
    });
  };
 
  return <Button onClick={handleSubscribe}>Subscribe</Button>;
}

The track function signature:

track(eventName: string, eventData?: object): void

• eventName: A clear name for the interaction (e.g., "signup", "video_play").
• eventData (Optional): A plain object with any relevant details. Keep it simple and avoid sensitive information.

Where to Use track

Use track inside:

• Event handlers (onClick, onSubmit etc.)
• useEffect hooks (for events triggered by component lifecycle or state changes)

Tracking custom events helps you understand user behavior deeply.