Docs > Roblox SDK

Roblox SDK

#

setup

Copy link to clipboard
#

Download and Installation

Copy link to clipboard
Download

GitHub ZIP installation

Unzip .zip file and inside Roblox Studio right-click on Workspace and click on ‘Insert from file…’ and select the unzipped .rbxmx file.

Roblox module page installation

On the GameAnalytics Roblox module page click on the ‘Get’ button. Inside Roblox Studio, select Workspace, open the Toolbox and select My Models and click on the GameAnalytics module to add it to Workspace.

Once the module has been installed inside Roblox Studio you need to do the following:

  1. Move the GameAnalytics script (together with its children) under ServerStorage
  2. Move the GameAnalyticsScript script under ServerScriptService
  3. Move the GameAnalyticsClient script under StarterPlayer/StarerPlayerScripts

It should end up looking like this:

#

initialize sdk

Copy link to clipboard
#

Using the SDK

Copy link to clipboard

Now we should be ready for adding code to activate the SDK!
There are 3 phases the SDK will go through.

  1. configuration
  2. initialization
  3. adding events or changing dimensions

Configuration calls configure settings for the SDK and some will not be able to be altered after initialize has been called.

Initialize call will start the SDK and activate the first session.

The configuration and initialization steps should be called when the application starts.

Once step 1 & 2 is done you can add events at different parts of the game code where some relevant action is happening.

#

Configuration

Copy link to clipboard
The configuration phase happens before initialization is called. The available configuration options are listed here.

  • build
  • available (allowed) custom dimensions
  • available (allowed) resource currencies
  • available (allowed) resource item types

Build

Build is used to specify the current version of your game. Specify it using a string. Recommended to use a 3 digit version like [major].[minor].[patch]

The build is specified in the GameAnalytics.Settings script. The build will automatically be configured from the GameAnalyticsScript script when the server starts. It should look something this:

Specifying allowed values

For certain types it is required to define a whitelist containing possible unique values during the configuration phase. When the SDK is being used (after initialization) only the specified values will be allowed. 20 values are allowed for each list.

ℹ️
Processing many unique dimension values can be taxing for our servers. A few games with a poor implementation can seriously increase our cost and affect stability. Games will be blocked if they submit too many unique dimension values. We have this configuration requirement to guide users into planning what dimension values can be used.

Available (allowed) custom dimensions, resource currencies and resource item types all need to be defined in the GameAnalytics.Settings script. These values will automatically be configured from the GameAnalyticsScript script when the server starts. It should look something this:

Remember to add the following line to your script whenever you need to call the SDK:

#

Initializing

Copy link to clipboard

When the server starts the GameAnalyticsScript script will initialize the SDK:

Make sure to set your key in the GameAnalytics.Settings script. It should look like this:

????
Don’t have any keys yet?
Head over here and register your game at the GameAnalytics website!

#

adding events

Copy link to clipboard

#

About

Copy link to clipboard

GameAnalytics feature the following event types.

Event Description
Business In-App Purchases supporting receipt validation on GA servers.
Resource Managing the flow of virtual currencies – like gems or lives.
Progression Level attempts with Start, Fail & Complete event.
Error Submit exception stack traces or custom error messages.
Design Submit custom event id’s. Useful for tracking metrics specifically needed for your game.

⚠️
Event id’s are strings separated by colons defining an event hierarchy – like “kill:robot:large”.

It is important to not generate an excessive amount of unique nodes possible in the event hierarchy tree.

A bad implementation example. [level_name]:[weapon_used]:[damage_done]

level_name could be 100 values, weapon_used could be 300 values and damage_done could be 1-5000 perhaps. This will generate an event hierarchy with:

100 * 300 * 5000 = 150M possible nodes.

This is far too many. Also the damage should be put as a value and not in the event string. The processing will perhaps be blocked for a game doing this and cause other problems when browsing our tool.

The maximum amount of unique nodes generated should be around 10k.

ℹ️
Please read our event guide here.
You will get the most benefit of GameAnalytics when understanding what and how to track.

#

Business

Copy link to clipboard

Business events are used to track real-money transactions.

Field Type Description Example
amount integer Amount in Robux (will be converted to USD 1$ = (1robux * 0.7) * 0.35). 100
itemType string The type / category of the item. GoldPacks
itemId string Specific item bought. 1000GoldPack
cartType string The game location of the purchase.
Max 10 unique values.
EndOfLevel

There is an option to automatically send business events when developer products and game passes (only in-game) are bought. It can be set in the GameAnalytics.Settings script like this:

If AutomaticSendBusinessEvents is set to true, then when the server starts the GameAnalyticsScript script will subscribe to game:GetService("MarketplaceService").PromptGamePassPurchaseFinished to send these automatic business events. Also you should call GameAnalytics:ProcessReceiptCallback(Info) within your own game:GetService("MarketplaceService").ProcessReceipt method.

#

Resource

Copy link to clipboard

Resource events are used to register the flow of your in-game economy (virtual currencies) – the sink (subtract) and the source (add) for each virtual currency.

ℹ️
Before calling the resource event it is needed to specify what discrete values can be used for currencies and item types in the Configuration phase.

source (add) Gem currency from an in-app purchase.

sink (subtract) Gem currency to buy an item.

sink (subtract) Gem currency to source (buy) some amount of another virtual currency (BeamBooster).

sink (subtract) 3 BeamBooster currency that were used during a level.

Field Type Description Example
flowType enum A defined enum for sourcing and sinking resources. GameAnalytics.EGAResourceFlowType.Sink
currency string The resource type/currency to track. Has to be one of the configured available resource currencies.
This string can only contain [A-Za-z] characters.
Gems, BeamBoosters, Coins
amount float Amount sourced or sinked. 0 or negative numbers are not allowed. 100.0
itemType string For sink events it can describe an item category you are buying (Weapons) or a place (Gameplay) the currency was consumed. For source events it can describe how the currency was gained. For example “IAP” (for in-app purchase) or from using another currency (Gems). Has to be one of the configured available itemTypes. Weapons, IAP, Gameplay, Boosters
itemId string For sink events it can describe the specific item (SwordOfFire) gained. If consumed during Gameplay you can simply use “Consumed”. For source events it describes how the player got the added currency. This could be buying a pack (BoosterPack5) or earned through Gameplay when completing a level (LevelEnd). BoosterPack5, SwordOfFire, LevelEnd, Coins400

⚠️
Be careful to not call the resource event too often!
In a game where the user collect coins fairly fast you should not call a Source event on each pickup. Instead you should count the coins and send a single Source event when the user either complete or fail the level.

ℹ️
For more information on the resource event go here.

#

Progression

Copy link to clipboard

Progression events are used to track attempts at completing some part of a game (level, area). A defined area follow a 3 tier hierarchy structure (could be world:stage:level) to indicate what part of the game the player is trying to complete.
When a player is starting a progression attempt a start event should be added.
When the player then finishes the attempt a fail or complete event should be added along with a score if needed.
Add a progression start event.

Or with score on complete or fail attempt:

It is not required to use all 3 if your game does not have them.

  • progression01
  • progression01 and progression02
  • progression01 and progression02 and progression03
Field Type Description Example
progressionStatus enum Status of added progression GameAnalytics.EGAProgressionStatus.Start GameAnalytics.EGAProgressionStatus.Fail GameAnalytics.EGAProgressionStatus.Complete
progression01 string Required progression location. World01
progression02 string Not required. Omit if needed else set to empty string. Stage01
progression03 string Not required. Omit if needed else set to empty string. Level01
score integer An optional score when a user completes or fails a progression attempt. Remember to set progression02 and/or progression03 if they are not used when using score parameter. 1023

ℹ️
For more information on the progression event go here.

#

Error

Copy link to clipboard

Error events are used to track custom errors in the game code. You can group the events by severity level and attach a message.
To add a custom error event call the following function:

Field Type Description Example
severity enum Severity of error GameAnalytics.EGAErrorSeverity.Debug
GameAnalytics.EGAErrorSeverity.Info
GameAnalytics.EGAErrorSeverity.Warning
GameAnalytics.EGAErrorSeverity.Error
GameAnalytics.EGAErrorSeverity.Critical
message string Error message (can be omitted) “Error when entering level12”

ℹ️
For more information on the error event go here.

#

Design

Copy link to clipboard

Every game is special. Therefore some needed events might not be covered by our other event types. The design event is available for you to add your own event-id hierarchy.

ℹ️
Please note that custom dimensions and progression filters will not be added on design and error events. Therefore you cannot (at the moment) filter by these when viewing design or error metrics.

To add a design event call the following method.

It is also possible to add a float value to the event.
This will (in addition to count) make the mean and sum aggregation available in the tool.

Field Type Description Example
eventId string The eventId is a hierarchy string that can consist of 1-5 segments separated by ‘:’. Each segment can have a max length of 32. “StartGame:ClassLevel1_5”, “StartGame:ClassLevel6_10”
value float A float event tied to the eventId. Will result in sum & mean values being available. 34.5

⚠️
It is important to not generate an excessive amount of unique nodes possible in the event hierarchy tree.

A bad implementation example.
[level_name]:[weapon_used]:[damage_done]

level_name could be 100 values, weapon_used could be 300 values and damage_done could be 1-5000 perhaps. This will generate an event hierarchy with:
100 * 300 * 5000 = 1.5M possible nodes.
This is far too many. Also the damage should be put as a value and not in the event string. The processing will perhaps be blocked for a game doing this and cause other problems when browsing our tool.
The maximum amount of unique nodes generated should be around 10k.

ℹ️
Please read our event guide here.
You will get the most benefit of GameAnalytics when understanding what and how to track.

#

command center

Copy link to clipboard

#

Configs

Copy link to clipboard

To manual check if Configs (CommandCenter) is ready (has been populated with values) you can call this:

To get values out of a populated Config use the following methods:

If the specified key is not found in the Config it will return the default value either “normal” or “custom” default value.

More info Configs please see here

#

Experiments (A/B testing)

Copy link to clipboard

To manual check if the Experiment (CommandCenter) is ready (has been populated with values) you can call this:

To get values out of a populated Experiment use the following methods:

If the specified key is not found in the Expermines it will return the default value either “normal” or “custom” default value.

More info Experiments please see here

#

custom dimensions

Copy link to clipboard

#

Using Custom Dimensions

Copy link to clipboard

GameAnalytics support the use of 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.

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

ℹ️
Read more about custom dimensions here.

#

debug & verify

Copy link to clipboard

#

Debugging

Copy link to clipboard
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.
Enable info log when implementing the SDK – remember to turn it off in production!

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.
Enable verbose log when troubleshooting events.

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.

Info and verbose logging will be automatically set from the EnableInfoLog and EnableVerboseLog values in the GameAnalytics.Settings script when the server starts, but can of course always be set on and off during the game at any time.

#

Verify Implementation

Copy link to clipboard

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.

ℹ️
Read more about the realtime dashboard and our data processing.

#

how does it work?

Copy link to clipboard

#

Session Handling

Copy link to clipboard

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

Session start

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

Session end

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

#

Event Queue

Copy link to clipboard

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

Interval

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

Copy link to clipboard

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.

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.

#

There is more!

Copy link to clipboard
There is much more to GameAnalytics and we suggest that you read our general documentation.
Please create a support ticket if you have any feedback like..

  • bugs
  • confusing features or UI
  • great ideas!

We hope you enjoy our service!

Contact support

We’ll get back to you ASAP.

Report a bug

Let us know more details.