npm package: @historymakers/datahero-analytics
Description: Lightweight analytics SDK for DataHero.
Author: History Makers
Latest version: 0.2.2

# @historymakers/datahero-analytics

Lightweight analytics SDK for DataHero.

## Create an analytics project

- Go to https://datahero.live/ and create an free analytics project.
- Copy the public key.

## Install

```bash
npm install @historymakers/datahero-analytics
```

## Next.js

Set:

```bash
NEXT_PUBLIC_DATAHERO_PUBLIC_KEY=your_public_key
```

Then:

```tsx
import { Analytics } from "@historymakers/datahero-analytics/next";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <Analytics />
      </body>
    </html>
  );
}
```

By default the SDK loads `https://datahero.live/tracking.js` and posts to
`https://datahero.live/api/v1/ingest`.

If you need a different production domain, a reverse proxy, or a self-hosted
setup, you can override it:

```tsx
<Analytics
  baseUrl="https://analytics.yourdomain.com"
  endpoint="https://analytics.yourdomain.com/api/v1/ingest"
/>
```

You can also set:

```bash
NEXT_PUBLIC_DATAHERO_BASE_URL=https://analytics.yourdomain.com
```

## Custom events

```ts
import { track } from "@historymakers/datahero-analytics";

track("signup_completed", {
  plan: "pro",
});
```

Custom properties must be flat key/value pairs. Supported values are strings,
numbers, booleans, and `null`.

## Identify users in the browser

```ts
import {
  identify,
  resetIdentity,
} from "@historymakers/datahero-analytics";

identify("user_123", {
  email: "person@example.com",
  name: "Taylor",
  plan: "pro",
});

resetIdentity();
```

## Server-side events

For API routes, background jobs, or Next.js server actions, use the dedicated
server entrypoint:

```ts
import { track } from "@historymakers/datahero-analytics/server";

await track(
  "purchase_completed",
  {
    plan: "pro",
    revenue: 49.99,
  },
  {
    serverKey: process.env.DATAHERO_SERVER_KEY,
    userId: "user_123",
    context: {
      visitorId: "v_123",
      sessionId: "s_123",
      url: "https://example.com/checkout/success",
    },
  }
);
```

You can also create a reusable client:

```ts
import { createServerAnalytics } from "@historymakers/datahero-analytics/server";

const analytics = createServerAnalytics({
  serverKey: process.env.DATAHERO_SERVER_KEY!,
});

await analytics.track("invoice_paid", {
  amount: 199,
});
```

You can also identify users from the backend:

```ts
import { identify } from "@historymakers/datahero-analytics/server";

await identify(
  "user_123",
  {
    email: "person@example.com",
    name: "Taylor",
  },
  {
    serverKey: process.env.DATAHERO_SERVER_KEY,
    context: {
      visitorId: "v_123",
    },
  }
);
```

By default the server entrypoint posts to `https://datahero.live/api/v1/events`.
Override it with `baseUrl`, `endpoint`, `identifyEndpoint`, or
`DATAHERO_BASE_URL`.

Server-side authentication uses your project server key:

```bash
DATAHERO_SERVER_KEY=dhsk_your_project_secret
```

## Payment attribution context

```ts
import { getTrackingContext } from "@historymakers/datahero-analytics";

const tracking = getTrackingContext();
```

`getTrackingContext()` returns the same `visitorId` and `sessionId` used by the
tracker, the current `identifiedUserId`, plus the current URL, path, referrer,
and UTM values so your checkout backend can forward them into payment metadata,
the DataHero Payment API, or server-side event tracking.

## Production notes

- If your site uses a strict CSP, allow the analytics origin in `script-src` and
  `connect-src`.
- If you use your own proxy domain, make sure both `/tracking.js` and
  `/api/v1/ingest` are reachable from the browser.