Documentation

SDK API Reference

Exports from @realanalytics/sdk

Core exports

import {
  createClient,
  defineEvents,
  p,
  defineDashboard,
  widget,
  controls,
  defineCohorts,
  palettes,
  chartColors,
  resolveColor,
  getPaletteColor,
  getColorScale,
  validateDashboard,
  validateWidget,
  isBuiltinEvent,
} from '@realanalytics/sdk'

createClient(config)

Collection is denied by default. Pass the visitor's consent decision before tracking; calls made before analytics consent is granted are discarded. See Browser & Consent for consent manager setup and stored decisions.

const analytics = createClient({
  publicKey: 'pk_live_xxx',
  endpoint: 'https://realanalytics-ingest.ryanerkal1.workers.dev',
  autocapture: true,
})

Client methods

track(event, properties?)
identify(userId, traits?)
setUserProperties(properties)
reset()
setConsent(input, stringSource?)
optIn()
optOut()
getConsent()
flush()
getDistinctId()
getPersonId()
getSessionId()
getQueueSize()
shutdown()

ConsentInput accepts 'granted', 'denied' or a ConsentUpdate object. The object requires analytics and a source label; adUserData, adPersonalization and recordedAt are optional. Purpose values accept booleans or 'granted' | 'denied' | 'unknown'. Pass the consent manager's actual decision; do not grant consent automatically.

defineEvents()

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

Property builders (`p`)

Schema properties are deliberately limited to strings, numbers, booleans, and string enums. Arrays, objects, dates, and null are not supported property definitions.

p.string()
p.number()
p.boolean()
p.enum([...])
.required() on any property builder

defineDashboard()

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',
    }),
  ],
})

Widget builders

widget.metric()
widget.timeSeries()
widget.breakdown()
widget.barChart()
widget.pieChart()
widget.funnel()

defineCohorts()

const cohorts = defineCohorts({
  paid_users: {
    name: 'Paid Users',
    filter: { plan: { $in: ['pro', 'enterprise'] } },
  },
})

Color helpers

const first = getPaletteColor(palettes.default, 0)
const scale = getColorScale('accessible', 6)
const resolved = resolveColor(chartColors.positive, false)

Schema validators

const result = validateDashboard(dashboardConfig)
if (!result.success) {
  console.error(result.error)
}

Type exports

import type {
  ClientConfig,
  ConsentConfig,
  ConsentInput,
  ConsentUpdate,
  ConsentSnapshot,
  ClientEventPayload,
  AutocaptureOptions,
  RetryConfig,
  DashboardConfig,
  WidgetConfig,
  BuiltinEvents,
  BuiltinEventName,
} from '@realanalytics/sdk'