API reference

Analytics

The global singleton for tracking events and views. Import it from @robojs/analytics.

import { Analytics } from '@robojs/analytics'

import { Analytics } from '@robojs/analytics'

The Analytics object is frozen at runtime. It cannot be modified or extended.

`Analytics.event(name, options?)`

Track a custom event.

Analytics.event(name: string, options?: EventOptions): Promise<void> | void

Analytics.event(name, options): Promise<void> | void

Parameter	Type	Description
`name`	`string`	Event name (e.g., `'button_click'`, `'purchase'`)
`options`	`EventOptions`	Optional metadata for the event

Analytics.event('feature_used', {
	sessionId: interaction.channelId,
	userId: interaction.user.id,
	data: { feature: 'leaderboard' }
})

Analytics.event('feature_used', {
	sessionId: interaction.channelId,
	userId: interaction.user.id,
	data: { feature: 'leaderboard' }
})

`Analytics.view(page, options?)`

Track a page or screen view.

Analytics.view(page: string, options?: ViewOptions): Promise<void> | void

Analytics.view(page, options): Promise<void> | void

Parameter	Type	Description
`page`	`string`	Page or screen name (e.g., `'Dashboard'`, `'Settings'`)
`options`	`ViewOptions`	Optional metadata for the view

Analytics.view('Settings Page', {
	sessionId: interaction.channelId,
	userId: interaction.user.id
})

Analytics.view('Settings Page', {
	sessionId: interaction.channelId,
	userId: interaction.user.id
})

`Analytics.isReady()`

Check whether an analytics engine has been initialized.

Analytics.isReady(): boolean

Analytics.isReady(): boolean

Returns true after the plugin's start lifecycle hook has successfully set an engine. Returns false if no engine is configured or the hook hasn't run yet.

if (Analytics.isReady()) {
	Analytics.event('safe_event')
}

if (Analytics.isReady()) {
	Analytics.event('safe_event')
}

Calling Analytics.event() or Analytics.view() before initialization throws a TypeError. Use Analytics.isReady() to guard against this.

EventOptions

Options for Analytics.event(). All fields are optional.

interface EventOptions {
	action?: string
	actionType?: string
	data?: unknown
	domain?: string
	label?: string
	name?: string
	referrer?: string
	revenue?: { currency: string; amount: number | string }
	sessionId?: string
	type?: string
	url?: string
	userId?: number | string
}

Prop

Type

ViewOptions

Options for Analytics.view(). Extends EventOptions with two additional fields.

interface ViewOptions extends EventOptions {
	element?: string
	elementId?: string
}

Prop

Type

These fields exist for custom engine implementations that need element-level view tracking.

GoogleAnalytics

Google Analytics Measurement Protocol v4 engine.

import { GoogleAnalytics } from '@robojs/analytics'

import { GoogleAnalytics } from '@robojs/analytics'

Constructor

new GoogleAnalytics(options?: GoogleAnalyticsOptions)

new GoogleAnalytics(options?: GoogleAnalyticsOptions)

Option	Type	Env var fallback	Description
`measureId`	`string`	`GOOGLE_ANALYTICS_MEASURE_ID`	GA4 Measurement ID (e.g., `G-XXXXXXXXX`)
`token`	`string`	`GOOGLE_ANALYTICS_SECRET`	Measurement Protocol API Secret

Constructor options take priority over environment variables.

const ga = new GoogleAnalytics({
	measureId: 'G-XXXXXXXXX',
	token: 'your-api-secret'
})

const ga = new GoogleAnalytics({
	measureId: 'G-XXXXXXXXX',
	token: 'your-api-secret'
})

Methods

Inherits event(name, options?) and view(page, options?) from BaseEngine.

event() sends a POST to /mp/collect with the event name and mapped parameters.
view() sends a page_view event with page_title set to the page name.

PlausibleAnalytics

Plausible Events API engine.

import { PlausibleAnalytics } from '@robojs/analytics'

import { PlausibleAnalytics } from '@robojs/analytics'

Constructor

new PlausibleAnalytics(domain?: string)

new PlausibleAnalytics(domain?: string)

Parameter	Type	Env var fallback	Description
`domain`	`string`	`PLAUSIBLE_DOMAIN`	Site domain registered in Plausible

const plausible = new PlausibleAnalytics('example.com')

const plausible = new PlausibleAnalytics('example.com')

Methods

Inherits event(name, options?) and view(page, options?) from BaseEngine.

event() sends a POST to /api/event with the event name and domain. Throws if data exceeds 30 fields.
view() sends a pageview event with a slugified URL built from the page name.

ManyEngines

Broadcasts events to multiple engines in parallel.

import { ManyEngines } from '@robojs/analytics'

import { ManyEngines } from '@robojs/analytics'

Constructor

new ManyEngines(...engines: BaseEngine[])

new ManyEngines(...engines: BaseEngine[])

Accepts any number of BaseEngine instances.

const multi = new ManyEngines(
	new GoogleAnalytics(),
	new PlausibleAnalytics('example.com')
)

const multi = new ManyEngines(
	new GoogleAnalytics(),
	new PlausibleAnalytics('example.com')
)

Methods

Inherits event(name, options?) and view(page, options?) from BaseEngine.

Both methods call the corresponding method on every engine via Promise.all(). If any engine rejects, the entire call rejects.

BaseEngine

Abstract base class for all analytics engines. Extend this to create custom providers.

abstract class BaseEngine {
	abstract event(name: string, options?: EventOptions): Promise<void> | void
	abstract view(page: string, options?: ViewOptions): Promise<void> | void
}

class BaseEngine {
	event(name, options) { /* abstract */ }
	view(page, options) { /* abstract */ }
}

See Custom engines for implementation details.

Next Steps

Configuration

Plugin options and environment variables.

Custom engines

Build your own analytics provider.

API reference

Configuration

Custom engines

On this page