Configuration Reference

All configuration properties in AnalyticsConfig are optional. When omitted, the engine uses defaults designed to minimize network traffic and memory consumption while ensuring zero frame hitching.

local Analytics = AnalyticsModule.init({
    debugMode = false,
    batchSize = 25,
    flushIntervalSeconds = 10,
    -- ... other overrides
})

Configuration Properties

`debugMode`

Type: boolean
Default: false
Description: When enabled, registers the DebugConsole exporter, which prints formatted batches of events directly to the Studio Output Window.
Recommendation: Set to true during local Studio testing and false in live games to prevent output log pollution.

`autoTrackSessions`

Type: boolean
Default: true
Description: Automatically records SessionStart, SessionEnd, active duration (excluding AFK periods), and duration distribution buckets (<1m, 1-5m, 5-15m, etc.).

`autoTrackServerUptime`

Type: boolean
Default: true
Description: Automatically logs ServerInit, ServerShutdown, peak player count, total uptime, and periodic ServerHeartbeat health snapshots.

`autoTrackBadges`

Type: boolean
Default: true
Description: Enables badge telemetry and the Analytics:AwardBadge helper method. Automatically computes player time-to-earn and checks badge ownership beforehand.

`autoTrackErrors`

Type: boolean
Default: true
Description: Hooks ScriptContext.Error on the server and receives forwarded errors from the client SDK. Employs logarithmic throttling to prevent flood-logging recurring errors.

`enableRetentionTracking`

Type: boolean
Default: true
Description: Uses DataStoreService to maintain persistent player visit histories. Distinguishes new vs. returning visitors and tracks D1, D3, D7, D14, and D30 return milestones.
Note: Requires Enable Studio Access to API Services to be toggled on in Game Settings when testing retention cohorts in Studio.

`retentionDataStoreName`

Type: string
Default: "AnalyticsModule_Retention_v1"
Description: The DataStore name used to persist player retention records.
Tip: Change this string if you wish to reset or wipe cohort testing records without deleting production data.

`autoTrackDemographics`

Type: boolean
Default: true
Description: Profiles client platform (PC, Mobile, Tablet, Console, VR), input device type, screen resolution, locale, and network latency on join.

`autoTrackDeaths`

Type: boolean
Default: true
Description: Monitors Humanoid.Died events on character models to capture death coordinates $(X, Y, Z)$, killer player/NPC, equipped weapon, and lifespan.

`serverHeartbeatIntervalSeconds`

Type: number
Default: 60
Description: Frequency in seconds at which server health snapshots (ServerHeartbeat) are emitted with memory usage (Stats:GetTotalMemoryUsageMb()) and average frame rate.

`afkThresholdSeconds`

Type: number
Default: 120
Description: Inactivity duration in seconds before a player is considered idle/AFK. Idle time is subtracted from total session playtime when calculating activeDurationSeconds.

`batchSize`

Type: number
Default: 25
Description: Maximum number of telemetry events coalesced into a single export batch. If the buffer reaches this threshold, an asynchronous batch flush is triggered immediately.

`flushIntervalSeconds`

Type: number
Default: 10
Description: Periodic timer interval (in seconds) to flush any buffered events to registered exporters.

`useRobloxAnalytics`

Type: boolean
Default: true
Description: Automatically routes economy, progression, and custom events to Roblox’s native AnalyticsService for viewing on the Creator Hub Analytics dashboard.

`httpEndpoint`

Type: string?
Default: nil
Description: HTTPS URL to an external telemetry ingest endpoint (e.g. Datadog, PostHog, or custom Node.js/Go backend). When provided, registers HttpExporter automatically.

`httpApiKey`

Type: string?
Default: nil
Description: Optional API key or bearer token forwarded in the Authorization: Bearer <key> and X-API-Key: <key> headers for HTTP exports.

`maxQueueSize`

Type: number
Default: 500
Description: Hard cap on the in-memory event buffer. If an exporter fails or network outages occur, older events are pruned first to prevent memory leaks.

Recommended Configuration Presets

1. Studio Development & Testing

Optimized for immediate feedback in the output window with rapid flushes:

local Analytics = AnalyticsModule.init({
    debugMode = true,
    batchSize = 5,
    flushIntervalSeconds = 5,
    serverHeartbeatIntervalSeconds = 30,
})

2. Standard Production (Roblox Creator Hub)

Default configuration ideal for most Roblox experiences:

local Analytics = AnalyticsModule.init({
    debugMode = false,
    useRobloxAnalytics = true,
    batchSize = 25,
    flushIntervalSeconds = 10,
    serverHeartbeatIntervalSeconds = 60,
})

3. High-Load / 100-Player Experiences

Larger batching thresholds to minimize CPU overhead and maximize payload compression:

local Analytics = AnalyticsModule.init({
    debugMode = false,
    batchSize = 50,
    flushIntervalSeconds = 20,
    serverHeartbeatIntervalSeconds = 120,
    maxQueueSize = 1000,
})