DataHero Docs

Integrate DataHero into web products, backends, and checkouts

Public documentation for teams and AI agents. It mirrors the dashboard integration guide with safe placeholders and the exact SDK, events, identify, and payment contract.

Start integration Open my project

Quick install

Environment variables and official SDK

.env + install

npm install @historymakers/datahero-analytics

NEXT_PUBLIC_DATAHERO_PUBLIC_KEY=pk_live_your_project_public_key
NEXT_PUBLIC_DATAHERO_BASE_URL=https://datahero.live
DATAHERO_SERVER_KEY=dhsk_your_project_server_key

Integration overview

The minimum a human or AI agent needs to connect a product to DataHero.

Project keys

The public key identifies the project from the browser. The server key authenticates private events and payments from the backend.

Data DataHero joins

Pageviews, events, identified user, visitorId, sessionId, UTMs, flags, and payment signals.

Payment attribution

Use Stripe metadata, a prior context registration, or the direct Payment API.

Public endpoint contract

Use these endpoints when you are outside the project dashboard.

Use	Method	URL	Auth
Tracker script	GET	https://datahero.live/tracking.js	Browser
Pageviews and web events	POST	https://datahero.live/api/v1/ingest	Public key
Identify	POST	https://datahero.live/api/v1/identify	Public key or server key
Server-side events	POST	https://datahero.live/api/v1/events	Server key
Payment context	POST	https://datahero.live/api/v1/payments/context	Server key
Manual payments	POST	https://datahero.live/api/v1/payments	Server key
Stripe webhook	POST	https://datahero.live/api/v1/payments/stripe/your_stripe_integration_token	Stripe signing secret

Next.js and web SDK

Install the tracker and enable pageviews, events, identify, and flags from the frontend.

Environment variables

NEXT_PUBLIC_DATAHERO_PUBLIC_KEY=pk_live_your_project_public_key
NEXT_PUBLIC_DATAHERO_BASE_URL=https://datahero.live
DATAHERO_SERVER_KEY=dhsk_your_project_server_key

app/layout.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>
  );
}

Events, identify, and flags

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

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

identify(user.id, {
  email: user.email,
  name: user.name,
  plan: user.plan,
});

setFlags({
  pricing_variant: "new_design",
  checkout_flow: "simplified",
});

await signOut();
resetIdentity();

Backend and private events

Use the server key to send authenticated events from APIs, jobs, or server actions.

Server-side events

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

await track(
  "purchase_completed",
  {
    plan: "pro",
    amount: 99,
  },
  {
    serverKey: process.env.DATAHERO_SERVER_KEY,
    userId: customer.id,
    context: tracking ?? undefined,
  }
);

Server-side identify

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

await identify(
  customer.id,
  {
    email: customer.email,
    name: customer.name,
  },
  {
    serverKey: process.env.DATAHERO_SERVER_KEY,
    context: tracking ?? undefined,
  }
);

Keep DATAHERO_SERVER_KEY on the server only. Never expose it in browser bundles, NEXT_PUBLIC_* variables, or public metadata.

Payments and attribution

Connect Stripe or a custom payment API without losing visitor, session, user, or UTM context.

Capture context before checkout

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

const tracking = getTrackingContext();

await fetch("/api/checkout/start", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    planId: "pro",
    tracking,
  }),
});

const tracking = body.tracking;
const checkoutId = checkout.id;

await fetch("https://datahero.live/api/v1/payments/context", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.DATAHERO_SERVER_KEY}`,
  },
  body: JSON.stringify({
    checkoutId,
    customerId: customer.id,
    customerEmailSha256: customer.emailSha256,
    ...tracking,
  }),
});

Stripe metadata

const session = await stripe.checkout.sessions.create({
  mode: "payment",
  line_items: [...],
  metadata: {
    dataheroIdentifiedUserId: tracking.identifiedUserId,
    dataheroVisitorId: tracking.visitorId,
    dataheroSessionId: tracking.sessionId,
    dataheroCheckoutId: checkout.id,
    dataheroCustomerId: customer.id,
    dataheroCustomerEmailSha256: customer.emailSha256,
  },
});

Direct Payment API

await fetch("https://datahero.live/api/v1/payments", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.DATAHERO_SERVER_KEY}`,
  },
  body: JSON.stringify({
    provider: "custom",
    externalPaymentId: order.id,
    amount: order.total,
    currency: "USD",
    occurredAt: new Date().toISOString(),
    checkoutId: checkout.id,
    customerId: customer.id,
    customerEmailSha256: customer.emailSha256,
    ...tracking,
  }),
});

AI agent guide

Operational checklist for automating the install in customer repositories.

Automatic implementation checklist

1Detect the framework and package manager; install @historymakers/datahero-analytics.
2Add NEXT_PUBLIC_DATAHERO_PUBLIC_KEY and DATAHERO_SERVER_KEY without hardcoding secrets.
3Mount <Analytics /> exactly once in the root layout or equivalent app shell.
4After login, call identify(user.id, traits); on logout call resetIdentity().
5Before checkout starts, read getTrackingContext() and send it to the backend.
6In the backend, persist payment context or copy datahero* fields into Stripe metadata.
7For private events, use @historymakers/datahero-analytics/server with serverKey.
8Validate in the dashboard that pageviews, events, identify, and payments appear in the correct project.

Validation criteria

Pageviews appear in the correct project using the public key.

Custom events accept only flat properties: string, number, boolean, or null.

Identify preserves the userId across sessions and resetIdentity clears it on logout.

Payments arrive with checkoutId, paymentIntentId, customerId, or customerEmailSha256.