Plausible

The plugin uses the Plausible Events API to send events server-side. Plausible is privacy-focused, cookie-free, and GDPR-compliant by default.

Setup

PLAUSIBLE_DOMAIN="example.com"

    import { Analytics } from '@robojs/analytics'

    Analytics.event('command_used', {
    	data: { command: 'ping' }
    })

    import { Analytics } from '@robojs/analytics'

    Analytics.event('command_used', {
    	data: { command: 'ping' }
    })

How it works

Each call to Analytics.event() or Analytics.view() sends a POST request to the Plausible Events API:

https://plausible.io/api/event

Event mapping

The plugin maps EventOptions fields to the Plausible payload:

Fields like sessionId, userId, revenue, action, actionType, label, and type are not used by the Plausible engine directly. Include them in data if you want them as custom properties.

Page views

Analytics.view() sends a pageview event. The page name is converted to a URL-safe slug and appended to the domain:

Analytics.view('Settings Page')
// URL becomes: https://example.com/settings-page

Analytics.view('Settings Page')
// URL becomes: https://example.com/settings-page

The slugification normalizes diacritics, removes special characters, and converts spaces to hyphens.

Custom properties

Pass custom properties through the data field:

Analytics.event('feature_used', {
	data: {
		feature: 'leaderboard',
		guild_size: 'large',
		user_role: 'admin'
	}
})

Analytics.event('feature_used', {
	data: {
		feature: 'leaderboard',
		guild_size: 'large',
		user_role: 'admin'
	}
})

Domain override

Override the configured domain for a specific event:

Analytics.event('cross_site_action', {
	domain: 'other-site.com',
	data: { source: 'discord-bot' }
})

Analytics.event('cross_site_action', {
	domain: 'other-site.com',
	data: { source: 'discord-bot' }
})

URL override

Override the auto-generated URL:

Analytics.view('Custom Page', {
	url: 'https://example.com/custom/path'
})

Analytics.view('Custom Page', {
	url: 'https://example.com/custom/path'
})

Request headers

The plugin sends hardcoded headers with each request:

These headers are required by the Plausible API. The X-Forwarded-For and User-Agent values are static since server-side events don't have a real browser context.

Programmatic configuration

Instead of environment variables, pass the domain directly to the constructor:

import { PlausibleAnalytics } from '@robojs/analytics'

export default {
	engine: new PlausibleAnalytics('example.com')
}

import { PlausibleAnalytics } from '@robojs/analytics'

export default {
	engine: new PlausibleAnalytics('example.com')
}

Constructor options take priority over the PLAUSIBLE_DOMAIN environment variable.

Error handling

The Plausible engine handles errors as follows:

• Missing event name: Logs an error and returns early. No exception thrown.
• Data exceeds 30 fields: Throws an Error. This propagates to the caller.
• API errors: Caught internally and logged as a warning.
• Missing domain: No explicit validation. Results in malformed URLs.

Troubleshooting

Events not appearing in Plausible dashboard

• Verify the domain in your .env matches exactly what you registered in Plausible.
• Domain mismatches cause events to be silently ignored by the Plausible API.

Error about exceeding 30 fields

• Reduce the number of properties in your data object. Split large payloads across multiple events if needed.

Next Steps