Announcing the Analytics Package for Makerkit

Hey there, Makerkit community! 👋

I am thrilled to announce a new addition to our SaaS starter kit: the brand new Analytics package! 🎉

Understanding user behavior is key to growth and success. That's why I have developed a powerful, flexible analytics system that seamlessly integrates with your Makerkit project - and any analytics service you choose to use.

Introducing the Analytics Package

Our new Analytics package brings two major components to the table:

Analytics API: A clean, consistent interface for tracking user behavior and app usage.
App Events System: A centralized approach to emitting and handling important app-wide occurrences.

The Power of Flexibility

We know that every SaaS app is unique, and your analytics needs might change over time. That's why we've built our Analytics package with flexibility in mind:

Provider Agnostic: Not locked into any specific analytics service
Extensible: Easily create custom analytics providers
Centralized: Use App Events for a clean, maintainable approach to tracking
Reusable: Share common tracking logic across your app with ease

Key Features and Code Examples

Let's dive into some key features with code snippets to show you just how easy it is to use the new Analytics package:

User Identification

Associate actions with specific users:


import { analytics } from '@kit/analytics';
 
void analytics.identify(userId, {
  email: user.email,
  plan: user.subscriptionPlan,
});

Event Tracking

Record important user interactions:


void analytics.trackEvent('Button Clicked', {
  buttonName: 'Submit',
  page: 'Sign Up',
});

Automatic Page Views

Built-in tracking for Next.js route changes (no extra code needed!).

Custom Events

Extend the system with your own event types:


import { useAppEvents } from '@kit/shared/events';
 
interface MyAppEvents {
  'feature.used': { featureName: string };
}
 
function MyComponent() {
  const { emit } = useAppEvents<MyAppEvents>();
 
  const handleFeatureUse = () => {
    emit({ type: 'feature.used', payload: { featureName: 'coolFeature' } });
  };
 
  // ...
}

Centralized Event Handling

Keep your analytics logic clean and maintainable:


const analyticsMapping: AnalyticsMapping = {
  'user.signedUp': (event) => {
    analytics.trackEvent(event.type, event.payload);
  },
  'feature.used': (event) => {
    analytics.trackEvent(event.type, event.payload);
  },
};

Default Tracked Events

Out of the box, Makerkit automatically tracks several key events to give you immediate insights into user behavior:

user.signedIn: Triggered when a user signs in. This event identifies the user in your analytics service, ensuring all subsequent events are properly associated.
user.signedUp: Fired when a new user signs up. Great for tracking your user acquisition funnel! (Note: This doesn't automatically work for social sign-ups.)
checkout.started: Triggered when a user initiates the checkout process. Perfect for analyzing your conversion funnel.
user.updated: Emitted when a user updates their authentication details.
Automatic Page Views: Makerkit tracks page views automatically as users navigate your app. No extra code required!

Here's a quick example of how these events are handled:


const analyticsMapping: AnalyticsMapping = {
  'user.signedIn': (event) => {
    const userId = event.payload.userId;
    if (userId) {
      analytics.identify(userId);
    }
  },
  'user.signedUp': (event) => {
    analytics.trackEvent(event.type, event.payload);
  },
  'checkout.started': (event) => {
    analytics.trackEvent(event.type, event.payload);
  },
  'user.updated': (event) => {
    analytics.trackEvent(event.type, event.payload);
  },
};

These default events give you a solid foundation for understanding user behavior, right out of the box. And remember, you can always add your own custom events to track the metrics that matter most to your specific SaaS!

Ready-to-Use Implementations

To get you started quickly, we're excited to provide three popular analytics implementations as plugins:

PostHog: For powerful, open-source product analytics
Umami: A simple, fast, privacy-focused alternative
Google Analytics: The tried-and-true analytics powerhouse

These plugins are ready to use out of the box, so you can start tracking user behavior right away!

Key Features

Our Analytics package is packed with features to help you track user interactions and monitor your users' behavior:

User Identification: Associate actions with specific users
Event Tracking: Record important user interactions
Automatic Page Views: Built-in tracking for Next.js route changes
Custom Events: Extend the system with your own event types
Best Practices Baked In: Consistent naming, relevant data tracking, and more

Getting Started with Analytics

Ready to supercharge your SaaS analytics? Check out our comprehensive documentation to start implementing the new Analytics package in your Makerkit project today!

Creating a Custom Analytics Provider

One of the most powerful features of our new Analytics package is its extensibility. If you need to integrate with a specific analytics service that isn't covered by our default plugins, you can easily create your own custom provider. Here's how:

Step 1: Implement the AnalyticsService Interface

First, create a new file for your custom analytics service that implements the AnalyticsService interface:


// packages/analytics/src/my-custom-analytics-service.ts
 
import { AnalyticsService } from './path-to-types';
 
class MyCustomAnalyticsService implements AnalyticsService {
  async initialize() {
    // Initialize your analytics service
    console.log('Custom analytics service initialized');
  }
 
  async identify(userId: string, traits?: Record<string, string>) {
    // Implement user identification
    console.log(`Identified user: ${userId}`, traits);
  }
 
  async trackPageView(url: string) {
    // Implement page view tracking
    console.log(`Page viewed: ${url}`);
  }
 
  async trackEvent(eventName: string, eventProperties?: Record<string, string | string[]>) {
    // Implement event tracking
    console.log(`Event tracked: ${eventName}`, eventProperties);
  }
}

Step 2: Register Your Custom Provider

Next, update your analytics configuration file to include your custom provider:


// packages/analytics/src/index.ts
 
import { createAnalyticsManager } from './analytics-manager';
import { MyCustomAnalyticsService } from './my-custom-analytics-service';
import type { AnalyticsManager } from './types';
 
export const analytics: AnalyticsManager = createAnalyticsManager({
  providers: {
    myCustom: (config) => new MyCustomAnalyticsService(config),
    // ... other providers
  },
});

Step 3: Use Your Custom Provider

Now you can use your custom analytics provider just like any other provider in the system:


import { analytics } from '@kit/analytics';
 
void analytics.identify('user123', { name: 'John Doe' });
void analytics.trackEvent('Feature Used', { featureName: 'Custom Analytics' });

That's it! You've successfully created and integrated a custom analytics provider. This approach allows you to connect Makerkit with any analytics service you prefer, giving you ultimate flexibility in how you track and analyze user behavior.