@getmetrica/analytics

Analytics plugin for Metrica -- a self-hosted, privacy-friendly analytics platform. Built on the analytics library.

Installation

npm install @getmetrica/analytics

Quick Start

The simplest way -- createAnalytics handles the analytics setup for you:

import { createAnalytics } from "@getmetrica/analytics";

const analytics = createAnalytics({
  apiKey: "your-project-api-key",
  apiUrl: "https://your-metrica-instance.com",
});

analytics.page();
analytics.track("button_clicked", { label: "Sign Up" });
analytics.identify("user-123", { plan: "pro" });

Advanced: Plugin Mode

If you already use DavidWells/analytics with other plugins, use the default export to add Metrica alongside them:

import Analytics from "analytics";
import metricaPlugin from "@getmetrica/analytics";
import googleAnalytics from "@analytics/google-analytics";

const analytics = Analytics({
  app: "my-app",
  plugins: [
    metricaPlugin({
      apiKey: "your-project-api-key",
      apiUrl: "https://your-metrica-instance.com",
    }),
    googleAnalytics({ measurementIds: ["G-XXXXXXXX"] }),
  ],
});

React Integration

import { createAnalytics } from "@getmetrica/analytics";
import { AnalyticsProvider, useAnalytics } from "use-analytics";

const analytics = createAnalytics({
  apiKey: "your-project-api-key",
  apiUrl: "https://your-metrica-instance.com",
  app: "my-react-app",
});

function App() {
  return (
    <AnalyticsProvider instance={analytics}>
      <Dashboard />
    </AnalyticsProvider>
  );
}

function Dashboard() {
  const { track, page } = useAnalytics();

  useEffect(() => {
    page();
  }, []);

  return <button onClick={() => track("cta_clicked")}>Get Started</button>;
}

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Project API key from your Metrica dashboard | | apiUrl | string | required | Base URL of your Metrica API server | | batchSize | number | 10 | Number of events to batch before sending | | flushInterval | number | 5000 | Interval in ms between automatic flushes | | sessionTimeout | number | 1800000 | Session inactivity timeout in ms (default 30 min) | | app | string | "app" | App name (only for createAnalytics) | | debug | boolean | false | Enable debug mode (only for createAnalytics) | | plugins | AnalyticsPlugin[] | [] | Extra plugins (only for createAnalytics) |

Exports

| Export | Description | |--------|-------------| | default (metricaPlugin) | Plugin factory for manual Analytics() setup | | createAnalytics | Pre-configured analytics instance with Metrica plugin | | Analytics | Re-exported analytics constructor for advanced usage | | AnalyticsInstance | TypeScript type for the analytics instance | | AnalyticsPlugin | TypeScript type for analytics plugins | | SessionManager | Session ID manager (sessionStorage-based) | | BatchTransport | Batched HTTP transport with circuit breaker |

Features

• Batched transport -- events are queued and sent in batches to reduce network requests
• sendBeacon support -- uses navigator.sendBeacon on page unload so no events are lost
• Session management -- automatic session tracking with configurable inactivity timeout
• Route normalization -- dynamic URL segments (UUIDs, numeric IDs) are collapsed into patterns like /users/:id
• Device detection -- automatically captures device type, browser, and OS
• Circuit breaker -- backs off after repeated failures to avoid flooding a down server

License

MIT