Documentation

Quick Start

Set up Realanalytics in a new or existing app

For a Meta-advertised lead form, follow the Meta setup guide after this page.

1. Install the CLI and SDK packages

The Realanalytics packages are not published to npm. Build them from the Realanalytics repository, then install the tarballs in the repository of the site you want to track.

# In the Realanalytics repository
bun run pack:local

# In your site repository; use the current filenames from manifest.json
npm install /path/to/realanalytics/dist/local-packages/realanalytics-sdk-0.1.0.tgz
npm install --save-dev /path/to/realanalytics/dist/local-packages/realanalytics-0.1.0.tgz

dist/local-packages/manifest.json lists the current package files. The installation guide covers the browser bundle and framework setup.

Run the installed CLI only

Every command below uses npx --no-install realanalytics, which runs the CLI installed from the tarball and fails if it is missing. Without the local install, omitting --no-install would ask npm to download a package named realanalytics from the public registry. That package is not this CLI.

2. Authenticate and scaffold analytics files

The CLI signs in to the dashboard named by REALANALYTICS_DASHBOARD_URL. Set it to the dashboard for the environment you are using; see the environment table.

npx --no-install realanalytics login
npx --no-install realanalytics init

init creates:

analytics/events.ts
analytics/attribution.ts
analytics/dashboards/overview.ts
.realanalytics/credentials.json, which holds the project secret key. Add .realanalytics/ to .gitignore.

3. Initialize the SDK

// lib/analytics.ts
import { createClient } from '@realanalytics/sdk'

export const analytics = createClient({
  publicKey: process.env.NEXT_PUBLIC_REALANALYTICS_KEY!,
  endpoint: process.env.NEXT_PUBLIC_REALANALYTICS_INGEST_URL!,
})

Collection starts denied. Before tracking, connect your CMP using the browser and consent guide. Calls made before analytics consent is granted are discarded.

4. Track a custom event

import { analytics } from '@/lib/analytics'

analytics.track('signup_completed', {
  plan: 'pro',
  source: 'pricing_page',
})

5. Define event schema and dashboard

// analytics/events.ts
import { defineEvents, p } from '@realanalytics/sdk'

export const events = defineEvents({
  signup_completed: {
    properties: {
      plan: p.enum(['free', 'pro', 'enterprise'] as const).required(),
      source: p.string(),
    },
    isConversion: true,
  },
})

// analytics/dashboards/overview.ts
import { defineDashboard, widget, controls } from '@realanalytics/sdk'

export default defineDashboard({
  id: 'overview',
  title: 'Overview',
  defaultDateRange: 'last_30_days',
  controls: [
    controls.dateRange({ editable: true }),
    controls.filter({ editable: true }),
  ],
  widgets: [
    widget.metric({
      id: 'signups',
      label: 'Signups',
      event: 'signup_completed',
      aggregation: 'count',
    }),
  ],
})

6. Deploy

npx --no-install realanalytics deploy --dry-run
npx --no-install realanalytics deploy