npm package: @getmetrica/analytics
Description: Client-side analytics SDK for Metrica — self-hosted analytics platform
Author: Metrica
Latest version: 0.0.5

# @getmetrica/analytics

Analytics plugin for [Metrica](https://github.com/pawanpaudel93/metrica) -- a self-hosted, privacy-friendly analytics platform. Built on the [analytics](https://github.com/DavidWells/analytics) library.

## Installation

```bash
npm install @getmetrica/analytics
```

## Quick Start

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

```js
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](https://github.com/DavidWells/analytics) with other plugins, use the default export to add Metrica alongside them:

```js
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

```jsx
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