Google Analytics

The plugin uses the Google Analytics Measurement Protocol v4 to send events server-side. No client-side scripts or cookies involved.

Setup

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

    import { Analytics } from '@robojs/analytics'

    Analytics.event('command_used', {
    	sessionId: interaction.channelId,
    	userId: interaction.user.id
    })

    import { Analytics } from '@robojs/analytics'

    Analytics.event('command_used', {
    	sessionId: interaction.channelId,
    	userId: interaction.user.id
    })

How it works

Each call to Analytics.event() or Analytics.view() sends a POST request to the Measurement Protocol endpoint:

https://www.google-analytics.com/mp/collect?measurement_id=G-XXX&api_secret=YYY

Event mapping

The plugin maps EventOptions fields to Google Analytics parameters:

Fields like domain, url, referrer, action, actionType, label, and type are not used by the Google Analytics engine. They exist in EventOptions for custom engine implementations.

Page views

Analytics.view() sends a page_view event with the page name mapped to page_title:

Analytics.view('Dashboard')
// Sends: { name: "page_view", params: { page_title: "Dashboard" } }

Analytics.view('Dashboard')
// Sends: { name: "page_view", params: { page_title: "Dashboard" } }

Session tracking

When you omit sessionId, the plugin generates a random 30-character alphanumeric client_id for each event. This means Google Analytics cannot correlate events from the same session.

For accurate session tracking, always pass a consistent sessionId:

// Use channel ID or guild ID as session identifier
Analytics.event('button_click', {
	sessionId: interaction.channelId ?? interaction.guildId,
	userId: interaction.user.id
})

// Use channel ID or guild ID identifier
Analytics.event('button_click', {
	sessionId: interaction.channelId ?? interaction.guildId,
	userId: interaction.user.id
})

Revenue tracking

Track revenue by including the revenue field. The currency and amount values are merged into the event parameters:

Analytics.event('purchase', {
	sessionId: interaction.guildId,
	userId: interaction.user.id,
	revenue: { currency: 'USD', amount: 4.99 },
	data: { item: 'premium_role' }
})

Analytics.event('purchase', {
	sessionId: interaction.guildId,
	userId: interaction.user.id,
	revenue: { currency: 'USD', amount: 4.99 },
	data: { item: 'premium_role' }
})

Custom event data

The data field passes through as GA event params. Use it for any custom dimensions:

Analytics.event('level_up', {
	sessionId: interaction.guildId,
	userId: interaction.user.id,
	data: {
		level: 10,
		xp_earned: 500,
		time_played: '2h30m'
	}
})

Analytics.event('level_up', {
	sessionId: interaction.guildId,
	userId: interaction.user.id,
	data: {
		level: 10,
		xp_earned: 500,
		time_played: '2h30m'
	}
})

Programmatic configuration

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

import { GoogleAnalytics } from '@robojs/analytics'

export default {
	engine: new GoogleAnalytics({
		measureId: 'G-XXXXXXXXX',
		token: 'your-api-secret'
	})
}

import { GoogleAnalytics } from '@robojs/analytics'

export default {
	engine: new GoogleAnalytics({
		measureId: 'G-XXXXXXXXX',
		token: 'your-api-secret'
	})
}

Constructor options take priority over environment variables.

Error handling

The Google Analytics engine handles errors gracefully:

• Missing credentials: Logs a warning and silently drops events. No errors thrown.
• API errors: Logs the HTTP status code and response text. No errors thrown.
• Successful events: Logged at debug level.

Check your Robo logs for [analytics] messages when troubleshooting.

Troubleshooting

Events not appearing in GA dashboard

• Verify your Measurement ID starts with G- (GA4 format).
• Check the API secret is correct and active.
• GA4 can take up to 24 hours to display server-side events. Use GA4 DebugView for real-time verification.

Missing session data

• Always pass sessionId for accurate session tracking. Without it, each event gets a random client_id.

Next Steps