myeasycms-v2/packages/analytics/AGENTS.md

@kit/analytics Package

Analytics package providing a unified interface for tracking events, page views, and user identification across multiple analytics providers.

Architecture

• AnalyticsManager: Central manager orchestrating multiple analytics providers
• AnalyticsService: Interface defining analytics operations (track, identify, pageView)
• Provider System: Pluggable providers (currently includes NullAnalyticsService)
• Client/Server Split: Separate entry points for client and server-side usage

Usage

Basic Import

// Client-side
import { analytics } from '@kit/analytics';

// Server-side
import { analytics } from '@kit/analytics/server';

Core Methods

// Track events
await analytics.trackEvent('button_clicked', { 
  button_id: 'signup',
  page: 'homepage' 
});

// Track page views
await analytics.trackPageView('/dashboard');

// Identify users
await analytics.identify('user123', { 
  email: 'user@example.com',
  plan: 'premium' 
});

Page views and user identification are handled by the plugin by default.

Creating Custom Providers

Implement the AnalyticsService interface:

import { AnalyticsService } from '@kit/analytics';

class CustomAnalyticsService implements AnalyticsService {
  async initialize(): Promise<void> {
    // Initialize your analytics service
  }

  async trackEvent(name: string, properties?: Record<string, string | string[]>): Promise<void> {
    // Track event implementation
  }

  async trackPageView(path: string): Promise<void> {
    // Track page view implementation
  }

  async identify(userId: string, traits?: Record<string, string>): Promise<void> {
    // Identify user implementation
  }
}

Default Behavior

• Uses NullAnalyticsService when no providers are active
• All methods return Promises that resolve to arrays of provider results
• Console debug logging when no active services or using null service
• Graceful error handling with console warnings for missing providers

Server-Side Analytics

When using PostHog, you can track events server-side for better reliability and privacy:

import { analytics } from '@kit/analytics/server';

// Server-side event tracking (e.g., in API routes)
export async function POST(request: Request) {
  // ... handle request
  
  // Track server-side events
  await analytics.trackEvent('api_call', {
    endpoint: '/api/users',
    method: 'POST',
    user_id: userId,
  });
  
  return Response.json({ success: true });
}

// Track user registration server-side
await analytics.identify(user.id, {
  email: user.email,
  created_at: user.created_at,
  plan: user.plan,
});