@robojs/analytics

Track usage patterns in your Robo with services like Google Analytics, Plausible, or a custom provider. Know how often commands are used, how many servers your bot joins, and more.

The plugin provides a unified Analytics API that works the same regardless of which analytics service you use. Switch providers or use multiple at once without changing your tracking code.

Features

Installation

Add the plugin to your Robo:

npx robo add @robojs/analytics@next

Or create a new project with the plugin pre-installed:

npx create-robo@next my-project -p @robojs/analytics@next

Quick start

The plugin detects which analytics service to use based on environment variables in your .env file.

GOOGLE_ANALYTICS_MEASURE_ID="G-123456789"
GOOGLE_ANALYTICS_SECRET="your-api-secret"

PLAUSIBLE_DOMAIN="example.com"

Start tracking events anywhere in your project:

import { Analytics } from '@robojs/analytics'

Analytics.event('button_click')
Analytics.view('Dashboard')

import { Analytics } from '@robojs/analytics'

Analytics.event('button_click')
Analytics.view('Dashboard')

That's it. The plugin handles initialization, service detection, and API calls automatically.

Auto-detection

The plugin detects which engine to use at startup:

Set both to send events to multiple services automatically. No config file needed.

Which service to choose?

Tracking events

Use Analytics.event() to track any action. Include sessionId and userId when possible for better accuracy.

import { Analytics } from '@robojs/analytics'
import type { ChatInputCommandInteraction } from 'discord.js'

export default (interaction: ChatInputCommandInteraction) => {
	const sessionId = interaction.channelId ?? interaction.guildId

	// Track with session and user context
	Analytics.event('feature_used', {
		sessionId,
		userId: interaction.user.id,
		data: { feature: 'leaderboard' }
	})

	return 'Tracked.'
}

import { Analytics } from '@robojs/analytics'

export default (interaction) => {
	const sessionId = interaction.channelId ?? interaction.guildId

	// Track with session and user context
	Analytics.event('feature_used', {
		sessionId,
		userId: interaction.user.id,
		data: { feature: 'leaderboard' }
	})

	return 'Tracked.'
}

Use Analytics.view() for page or screen views:

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

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

Check if the plugin has been initialized before calling:

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

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

Seed files

When you install the plugin with npx robo add, it can seed your project with starter tracking code:

The track-commands middleware is the most useful seed file. It intercepts every slash command, normalizes the name (replacing / and - with _), and sends it as an event with session and user context. No per-command tracking code needed.

Delete test-analytics.ts after verifying your setup works.

Next Steps