SDK Features

Debugging

The SDK is designed to be as silent as possible and use very few resources. You will therefore not get much information by default in your development console.

We have 2 different debug log types that can be enabled / disabled (at any time):

• info log
• verbose log

Info log

Short messages will be output when enabled explaining when some action is being performed by the SDK. Sometimes cropping text / values to make it more readable.

tip

Enable info log when implementing the SDK – remember to turn it off in production!

GameAnalytics:setEnabledInfoLog(true)

Sample output:

 Info/GameAnalytics: Add DESIGN event: {eventId:someEvent, value:0}
 Info/GameAnalytics: Add DESIGN event: {eventId:someOtherEvent, value:100}
 Info/GameAnalytics: Add ERROR event: {severity:info, message:This is some in}

Verbose Log

Console output when each event is added (all fields) in JSON string format. This is the data being submitted to the GA servers for each event.

tip

Enable verbose log when troubleshooting events.

GameAnalytics:setEnabledVerboseLog(true)

This can result in a lot of text. When troubleshooting/debugging events it is therefore recommended to enable/disable when performing the action that need inspection.

Troubleshooting example:

-- enable verbose log
GameAnalytics:setEnabledVerboseLog(true)
-- add event you need to troubleshoot / inspect
GameAnalytics:addDesignEvent({
    eventId = "Some:Event",
    value = 100
})
-- disable verbose log
GameAnalytics.setEnabledVerboseLog(false)

Info and verbose logging will be automatically set from the enableInfoLog and enableVerboseLog values in the GameAnalyticsServerInit script to automatically set them when the server starts like this:

GameAnalytics:initialize({
    enableInfoLog = true,
    enableVerboseLog = false
    -- more settings
})

…but can of course always be set on and off during the game at any time.

Verify Implementation

Enable the Info Log to verify that events are being sent from your game project without any issues being reported.

Events submitted should register after a minor delay in our realtime dashboard in the GameAnalytics tool. Please note that when testing inside Roblox Studio event are only sent using the sandbox API not the live API.

tip

Read more about the realtime dashboard and our data processing here.

Session Handling

Sessions are the concept of a user spending focused time in your game – from game launch to the user leaving the game.

Session start

Generate new session when a user enters the game. Add a session start event (a “user” event) for that user.

Session end

When a user exits the add a session_end event for that user. Submit queued events.

Event Queue

Whenever an event is added (and validated) it will be added to a queue.

Every 8 seconds the SDK will start a task for submitting queued events since last submit. This processing is done in a separate low-priority thread that will have minimum impact on performance.

Thread Handling

Almost every piece of this code is run using a dedicated low-priority serial thread queue to avoid UI lag or sudden performance spikes. The queue will execute each task sequentially. If the SDK add several tasks to the queue then each will be executed in turn. A task could be adding an event or submitting all queued events.

Consider this example with 3 calls.

-- Configure build version
GameAnalytics:configureBuild("alpha 0.1.0")

-- Initialize
GameAnalytics:initialize({
    gameKey = "[YOUR GAME KEY]",
    secretKey = "[YOUR SECRET KEY]"
})

-- Add Design event
GameAnalytics:addDesignEvent({
    eventId = "Some:Event"
})

The configureBuild is required to be called before initialize is completely finished. The design event call is required after initialize is finished. The queuing will make sure that each task is completely finished before proceeding to the next one.

Disable Error Events

Use the below snippet if you wish to stop error events from being sent to our collection servers:

GameAnalytics:setEnabledReportErrors(false)

Custom Dimensions

GameAnalytics support the use of up to 3 custom dimensions:

• Custom01
• Custom02
• Custom03

During the game it is possible to set the active value for each custom dimension dynamically. Once a dimension is set it will be persisted across sessions/game-start and automatically be added to all event categories. Remember you have to set the custom dimensions before initialzing the SDK (but after setting the available custom dimensions) to be able to add the dimensions to the first session start event.

Setting each custom dimension. To reset a set custom dimension simply just set it to empty string.

GameAnalytics:setCustomDimension01(player.UserId, "ninja")
GameAnalytics:setCustomDimension02(player.UserId, "dolphin")
GameAnalytics:setCustomDimension03(player.UserId, "horde")

-- reset Custom03 dimension
GameAnalytics:setCustomDimension03(player.UserId, "")

Field	Type	Description	Example
customDimension	string	One of the available dimension values set in the configuration phase. Will persist cross session. Set to empty string to reset.	ninja

tip

Read more about custom dimensions here