@historymakers/datahero-analytics

v0.2.2

Published

a month ago

Lightweight analytics SDK for DataHero.

0High
0Medium
0Low

historymakers

analytics datahero historymakers analytics-sdk tracking

@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

npm install @historymakers/datahero-analytics

Next.js

Set:

NEXT_PUBLIC_DATAHERO_PUBLIC_KEY=your_public_key

Then:

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:

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

You can also set:

NEXT_PUBLIC_DATAHERO_BASE_URL=https://analytics.yourdomain.com

Custom events

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

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

identify("user_123", {
  email: "[email protected]",
  name: "Taylor",
  plan: "pro",
});

resetIdentity();

Server-side events

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

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:

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:

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

await identify(
  "user_123",
  {
    email: "[email protected]",
    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:

DATAHERO_SERVER_KEY=dhsk_your_project_secret

Payment attribution context

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@historymakers/datahero-analytics

Create an analytics project

Install

Next.js

Custom events

Identify users in the browser

Server-side events

Payment attribution context

Production notes