@tjoc/analytics

A powerful analytics SDK for the TJOC platform, providing seamless integration with PostHog for event tracking, feature flags, and A/B testing. Supports both React and non-React environments.

Features

• 🔄 Easy PostHog Integration
• 🎯 Type-safe Event Tracking
• 🚩 Feature Flag Management
• 🧪 A/B Testing Support
• 👤 User Identification
• ⚛️ React Hooks for all features
• 🔌 Non-React Service API
• 🌐 Automatic Page View Tracking
• 💾 Configurable Data Persistence

Installation

pnpm add @tjoc/analytics

Quick Start

Direct Usage (Non-React)

import { analytics } from '@tjoc/analytics';

// Track an event
analytics.trackEvent('button_clicked', {
  buttonName: 'submit',
  page: 'checkout',
});

// Track a page view
analytics.trackPageView('/checkout', {
  referrer: '/cart',
});

// Identify a user
analytics.identify('user123', {
  name: 'John Doe',
  email: '[email protected]',
});

React Setup

import { AnalyticsProvider } from '@tjoc/analytics';

function App() {
  return (
    <AnalyticsProvider config={{
      apiKey: 'your-posthog-api-key',
      apiHost: 'your-posthog-host', // optional
      debug: process.env.NODE_ENV === 'development',
      capturePageView: true,
      persistence: 'localStorage'
    }}>
      {/* Your app components */}
    </AnalyticsProvider>
  );
}

React Hooks

Event Tracking

import { useTrackEvent } from '@tjoc/analytics';

function MyComponent() {
  const { trackEvent, trackPageView } = useTrackEvent('user123');

  const handleClick = () => {
    trackEvent('button_clicked', {
      buttonName: 'submit',
      page: 'checkout',
    });
  };

  useEffect(() => {
    trackPageView('/my-page');
  }, []);

  return <button onClick={handleClick}>Submit</button>;
}

Feature Flags

import { useFeatureFlag } from '@tjoc/analytics';

function MyComponent() {
  const { isEnabled, isLoading, error, refresh } = useFeatureFlag('new-feature');

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return isEnabled ? (
    <div>New Feature Enabled!</div>
  ) : (
    <div>Using Old Feature</div>
  );
}

A/B Testing

import { useExperiment } from '@tjoc/analytics';

function MyComponent() {
  const { variant, isLoading, error, refresh } = useExperiment('button-color');

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <button
      style={{ backgroundColor: variant === 'blue' ? '#0000FF' : '#FF0000' }}
    >
      Click Me
    </button>
  );
}

User Identification

import { useIdentify } from '@tjoc/analytics';

function ProfileComponent() {
  const identify = useIdentify('user123');

  useEffect(() => {
    identify({
      name: 'John Doe',
      email: '[email protected]',
      plan: 'premium',
    });
  }, []);

  return <div>Profile Content</div>;
}

Configuration

Analytics Config

interface AnalyticsConfig {
  apiKey: string; // PostHog API key
  apiHost: string; // PostHog API host
  host?: string; // Optional custom host
  debug?: boolean; // Enable debug logging
  capturePageView?: boolean; // Auto-capture page views
  persistence?: 'localStorage' | 'cookie' | 'memory'; // Data storage method
  provider?: AnalyticsProvider; // Optional custom provider
}

Event Properties

interface EventProperties {
  [key: string]: any;
  userId?: string; // Automatically added by hooks
}

interface UserProperties {
  [key: string]: any;
}

Best Practices

1. Event Naming

   • Use snake_case for consistency
   • Be descriptive and specific
   • Follow a pattern: object_action (e.g., button_clicked, form_submitted)

2. User Identification

   • Identify users as early as possible
   • Include relevant user properties
   • Use consistent user IDs across the platform

3. Feature Flags

   • Use for gradual rollouts
   • Implement fallback behavior
   • Handle loading and error states

4. Error Handling

   • Always handle loading states
   • Provide fallback UI for errors
   • Log analytics errors appropriately

5. Performance

   • Use memoization for event handlers
   • Batch events when possible
   • Consider network conditions

TypeScript Support

The package includes comprehensive TypeScript definitions. You can extend the default types:

declare module '@tjoc/analytics' {
  interface EventProperties {
    category?: string;
    value?: number;
    // Add custom properties
  }

  interface UserProperties {
    plan?: 'free' | 'premium';
    // Add custom user properties
  }
}

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT