Product analytics

analytics records declared product events and metrics under pseudonymised IDs, only with consent where it is required. Reach for it to learn which features people use and where they drop off.

Built for 0.3 (spec analytics). Declare each event and its props in main.yaml. Only declared events are accepted, and a person's events are recorded only with consent for their purpose.

analytics:
  to: [builtin]
  without-consent: drop
  buffer: 10000
  posthog: { host: eu.i.posthog.com, key: "secret:POSTHOG_KEY", regions: [eu] }
  min-group: 10
  events:
    checkout.started:
      purpose: analytics
      props: { plan: "enum(free, pro)", items: int }
  metrics:
    checkout.duration: { type: histogram, unit: ms, attrs: [plan] }

import { analytics } from "mainsdk";

analytics.track("checkout.started", { plan: "pro", items: 3 });

analytics:
  driver: builtin

Quick start

analytics:
  to: [builtin]
  events:
    checkout.started:
      purpose: analytics
      props: { plan: "enum(free, pro)" }

"use server";
import { analytics, auth } from "mainsdk";

export async function startCheckout(req: Request, plan: string) {
  const session = await auth.require(req);
  analytics.track("checkout.started", { plan });   // the user and tenant come from the request
}

Configuration

analytics:
  to: [builtin]                  # builtin (on db) | posthog | otel; queries need builtin
  without-consent: drop          # drop (default) | aggregate
  min-group: 10                  # results for fewer people are hidden; may only be raised
  events:
    checkout.started:
      purpose: analytics
      props: { plan: "enum(free, pro)", items: int, coupon: "string?" }
  metrics:
    checkout.duration: { type: histogram, unit: ms, attrs: [plan] }
  posthog: { host: eu.i.posthog.com, key: secret:POSTHOG_KEY, regions: [eu] }

Provider keys go in as secret:NAME references. Consent comes from privacy, so there is no second banner. An undeclared event fails with MAIN-ANALYTICS-0001, and props that fail their type with MAIN-ANALYTICS-0002.

What you get

• Events recorded only with consent for their purpose, and only if main.yaml declares them with typed props.
• A built-in store in each tenant's region, with PostHog and any OpenTelemetry backend as optional drivers.
• Children's audiences counted as aggregates, with no id and no props beyond enums, booleans and integers.
• Queries for counts, active people, feature use, retention and funnels, with groups under min-group hidden.
• mainsdk analytics to ask the same questions from the terminal, and checks for undeclared events and identifying props.

Examples

Track page views in the browser

import { analytics } from "mainsdk";

// call it from your router's route-change hook, for example a React effect keyed on the pathname
export function onRouteChange(pathname: string) {
  analytics.page(pathname);
}

Track a server-side event from a job

import { analytics } from "mainsdk";

export function onSubscriptionRenewed(plan: string) {
  analytics.track("subscription.renewed", { plan });
}

Metrics and queries

Counters, gauges and histograms go out over OpenTelemetry. Active users by country, region or app version (the old stats) is a query too, see the example below. analytics.query(q) reads the built-in store for the current tenant: counts, active users, feature use, retention and funnels. Rows for fewer than min-group people are hidden.

import { analytics } from "mainsdk";

analytics.counter("exports.made").add(1, { format: "csv" });
analytics.gauge("queue.depth").set(12, { queue: "emails" });
analytics.histogram("checkout.duration").record(840, { plan: "pro" });

const result = await analytics.query({
  kind: "count", event: "checkout.started", by: ["day"], from: "2026-10-01", to: "2026-10-31",
});

Active users by country

import { analytics } from "mainsdk";

const byCountry = await analytics.query({
  kind: "active", window: "month", by: ["country"], from: "2026-10-01", to: "2026-10-31",
});

by takes country, region, version, plan, day, week or month.

Errors and checks

Swapping drivers

analytics:
  to: [posthog]   # was builtin

Your track and page calls stay the same. analytics.query() needs builtin, or it fails with MAIN-ANALYTICS-0007. Past events stay in the old tool.

Testing

createTestApp({ main: "./main.yaml" }) from the Testing kit runs analytics on an in-memory fake, so tests send nothing to your provider. Helpers to set consent on the fake and assert on tracked events arrive with the spec.

Security and privacy

• Nothing is sent without consent where it is required.
• Only pseudonymised user IDs leave your app, so erasing a user there is a mapping delete.
• Keep personal data out of event properties.
• On mobile, consent is decided on the device from phase 3 (spec expo-adapter).

FAQ

Can I send events to MainSDK Cloud? Yes, mainsdk is one of the drivers. Nothing goes to MainSDK Cloud without login and opt-in.

Do I need my own consent banner? No. Use privacy to record consent, or connect the consent platform you already run.

Next

• Privacy and data rights
• Feature flags