Analytics & Tracking
Relevant source files
The following files were used as context for generating this wiki page:
Analytics & Tracking in TREAD Talks monitors page traffic and product events to understand user engagement with faith-based content. The system integrates multiple providers, including Vercel Web Analytics for traffic and Segment for product event tracking.
The architecture separates concerns between infrastructure providers and client-side event capturing. Segment acts as a central hub, routing events to downstream destinations like Mixpanel via cloud-mode actions.
Sources: README.md:15-17, src/lib/analytics/client.ts
Core Infrastructure
The project utilizes three primary services for monitoring and data collection:
- Vercel Web Analytics: Tracks general page traffic and visitor metrics.
- Segment: Serves as the primary collector for product-specific events using the
@segment/analytics-nextlibrary. - Mixpanel: Functions as a destination for Segment data to perform deep product analysis.
Provider Configuration
| Provider | Purpose | Implementation |
|---|---|---|
| Vercel | Page traffic | <Analytics /> component in root layout |
| Segment | Event collection | AnalyticsBrowser from @segment/analytics-next |
| Mixpanel | Event analysis | Configured as Segment destination (Cloud-mode) |
Sources: README.md:15-17, src/app/layout.tsx:103, package.json:65
Client Tracking Implementation
Event tracking is managed through a client-side utility that wraps the Segment SDK. This utility handles asynchronous initialization and ensures events are dispatched correctly even if the SDK has not fully loaded.
Event Dispatch Flow
The system uses a dispatch queue to manage tracking tasks. This ensures that identification, page views, and custom events are processed in order.
The dispatch mechanism prevents event loss during initial page load by resolving a clientPromise before execution.
Sources: src/lib/analytics/client.ts:13-64
Tracking Functions
The src/lib/analytics/client.ts file exposes several core functions for tracking:
identify(userId, traits): Associates a user with specific identity traits like email, name, and role.page(): Records a page view event.captureEvent(event, properties): Sends a custom track event with associated metadata.reset(): Clears the current analytics session (typically used on logout).
Sources: src/lib/analytics/client.ts:85-131
Integration in UI Components
Tracking is integrated throughout the application via React components and providers.
Root Layout Integration
The RootLayout wraps the entire application in an AnalyticsProvider. It also explicitly renders the Vercel <Analytics /> component at the bottom of the document body.
// src/app/layout.tsx
export default function RootLayout({ children, sheet }) {
return (
<html lang="en">
<body>
<AnalyticsProvider>
{/* ... UI Components ... */}
</AnalyticsProvider>
<Analytics debug={false} />
</body>
</html>
);
}
Sources: src/app/layout.tsx:90-104
Feature-Specific Tracking
UI elements that represent user actions, such as sharing or favoriting a talk, trigger specific tracking events. These are often encapsulated in specialized button components.
ShareTalkButton: Tracks when a user shares content.FavoriteTalkButton: Monitors user preference for specific talks.FinishTalkButton: Tracks content consumption completion.
Sources: src/app/talks/[speakerSlug]/[talkSlug]/_components/talk-metadata-sidebar.tsx:75-78
Environment Configuration
Tracking behavior is controlled via environment variables to prevent development data from polluting production analytics.
NEXT_PUBLIC_SEGMENT_WRITE_KEY: Required for Segment to initialize. If missing, the client utility returnsundefinedand skips dispatching.- Vercel Environments: Segment is configured only for the Production environment in Vercel, skipping Preview builds to maintain data integrity.
Sources: src/lib/analytics/client.ts:7-9, README.md:27-30
Summary
The Analytics & Tracking system provides a robust framework for monitoring user behavior on the TREAD Talks platform. By leveraging Segment as a middleware, the application maintains a clean tracking API while allowing flexible routing to tools like Mixpanel and Vercel Analytics for both traffic and product insights.