Event Tracking

GameAnalytics features the following event types:

Event	Description
Ad	Ads shown and clicked, fill rate.
Business	In-App Purchases supporting receipt validation on GA servers.
Design	Submit custom event id’s. Useful for tracking metrics specifically needed for your game.
Error	Submit exception stack traces or custom error messages.
Health	Automatically submits health metrics related to your game such as FPS.
Impression	Impression data from different ad networks
Progression	Level attempts with Start, Fail & Complete event.
Resource	Managing the flow of virtual currencies - like gems or lives

tip

Read more about events here

Business

Business events are used to track real-money transactions.

Field	Type	Description	Example
amount	integer	Amount in Robux	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

The SDK will convert the specified Robux amount to USD before sending it our servers. Our servers expect all business event amounts to be in cents.

SDK conversion formula: USD cents = (1 Robux * 0.7) * 0.35.

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 GameAnalyticsServerInit script like this:

GameAnalytics:initialize({
    automaticSendBusinessEvents = true,
    -- more settings
})

If AutomaticSendBusinessEvents is set to true (true by default), then when the server starts the GameAnalytics 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 which then send a business event for you.

It is also possible to send a business event manually which can be done as shown below:

GameAnalytics:addBusinessEvent(Player.UserId, {
    amount = 100,
    itemType = "boost",
    itemId = "megaboost",
    cartType = "ingame"
})

If you want to disable AutomaticSendBusinessEvents it can be done like this from your script:

GameAnalytics:setEnabledAutomaticSendBusinessEvents(false)

tip

For more information about Business Events go here.

Resource Events

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.

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

GameAnalytics:addResourceEvent(Player.UserId, {
    flowType = GameAnalytics.EGAResourceFlowType.Source,
    currency = "Gems",
    amount = 400,
    itemType = "IAP",
    itemId = "Coins400"
})

sink (subtract) Gem currency to buy an item.

GameAnalytics:addResourceEvent(Player.UserId, {
    flowType = GameAnalytics.EGAResourceFlowType.Sink,
    currency = "Gems",
    amount = 400,
    itemType = "IAP",
    itemId = "Coins400"
})

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

GameAnalytics:addResourceEvent(Player.UserId, {
    flowType = GameAnalytics.EGAResourceFlowType.Sink,
    currency = "Gems",
    amount = 100,
    itemType = "Boosters",
    itemId = "BeamBooster5Pack"
})

GameAnalytics:addResourceEvent(Player.UserId, {
    flowType = GameAnalytics.EGAResourceFlowType.Source,
    currency = "BeamBooster",
    amount = 5,
    itemType = "Gems",
    itemId = "BeamBooster5Pack"
})

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

GameAnalytics:addResourceEvent(Player.UserId, {
    flowType = GameAnalytics.EGAResourceFlowType.Sink,
    currency = "BeamBooster",
    amount = 3,
    itemType = "Gameplay",
    itemId = "BeamBooster5Pack"
})

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

caution

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.

tip

For more info on Resource Events go here

Progression

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.

tip

When a player is starting a progression attempt a start event should be added.

tip

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.

GameAnalytics:addProgressionEvent(Player.UserId, {
    progressionStatus = GameAnalytics.EGAProgressionStatus.Start,
    progression01 = "world01",
    progression02 = "stage01",
    progression03 = "level01"
})

Or with score on complete or fail attempt:

GameAnalytics:addProgressionEvent(Player.UserId, {
    progressionStatus = GameAnalytics.EGAProgressionStatus.Complete,
    progression01 = "world01",
    progression02 = "stage01",
    progression03 = "level01",
    score = 100
})

Field	Type	Required	Description
progressionStatus	enum	yes	Start, Complete or Fail
progression01	string	yes	1st progression (e.g. world01).
progression02	string	no	2nd progression (e.g. level01).
progression03	string	no	3rd progression (e.g. phase01).
score	int	no	Score of the attempt

It is not required to use all 3 progression tiers if your game does not have them. Below you can find all the possible combinations you can use for progression events:

• progression01
• progression01 and progression02
• progression01 and progression02 and progression03

caution

At least progression01 must be set for such events (an empty value is not allowed).

info

Progressions need to be set in order (e.g: you cannot have only progression01 and progression03, nor progression02 and progression03, you are required to start from 01 and continue)

tip

For more information Progression Events go here

Error

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:

GameAnalytics:addErrorEvent(Player.UserId, {
    severity = GameAnalytics.EGAErrorSeverity.critical,
    message = "Something went bad in some of the smelly code!"
})

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”

tip

For more information on Error Events go here.

Design

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.

GameAnalytics:addDesignEvent(Player.UserId, {
    eventId = "Kill:Sword:Robot"
})

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.

GameAnalytics:addDesignEvent(Player.UserId, {
    eventId = "BossFights:FireLord:KillTimeUsed",
    value = 234
})

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

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

danger

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.

tip

For more information on Design Events go here.

Multi-Place Games

If you have a multi-place game and don’t want to end sessions in between places when teleporting.

First you need to do is to add the “gameanalytics teleport data” to you teleport data like this:

local playerIds = { playerId1, playerId2, ... }
local teleportData = {}

-- Add other teleport data...

teleportData = ga:addGameAnalyticsTeleportData(playerIds, teleportData)

-- Call teleport function with the updated teleport data

Remember all the player ids passed into ga:addGameAnalyticsTeleportData will be flagged as teleporting and will not get an end session event sent when Players.PlayerRemoving:Connect is called, so only call ga:addGameAnalyticsTeleportData when needed for actual teleporting.

Also remember to ga:initialize the SDK in the new place.

Localscript Events

Since the GameAnalytics SDK is only available on server side here how you would send events from localscripts:

Your server script in ServerScriptService:

local ServerStorage = game:GetService("ServerStorage")
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local myDesignEvent = Instance.new("RemoteEvent", ReplicatedStorage)
myDesignEvent.Name = "MyDesignEvent"
local myProgressionEvent = Instance.new("RemoteEvent", ReplicatedStorage)
myProgressionEvent.Name = "MyProgressionEvent"

local GameAnalytics = require(ServerStorage.GameAnalytics)

local function onMyDesignEventFired(player, myEventId)
    GameAnalytics:addDesignEvent(player.UserId, {
        eventId = myEventId
    })
end

myDesignEvent.OnServerEvent:Connect(onMyDesignEventFired)

local function onMyProgressionEventFired(player, myProgressionStatus, myProgression01, myProgression02, myProgression03, myScore)
    GameAnalytics:addProgressionEvent(player.UserId, {
        progressionStatus = myProgressionStatus,
        progression01 = myProgression01,
        progression02 = myProgression02,
        progression03 = myProgression03,
        score = myScore
    })
end

myProgressionEvent.OnServerEvent:Connect(onMyProgressionEventFired)

Your localscript:

local myDesignEvent = ReplicatedStorage:WaitForChild("MyDesignEvent")
local myProgressionEvent = ReplicatedStorage:WaitForChild("MyProgressionEvent")

local function myFunctionToSendEventFrom()
    myDesignEvent:FireServer("myEventId:goes:here")
    myProgressionEvent:FireServer("Start", "world01", "stage01", "level01", 100)
end

In the example above used design and progression events to demonstrate how to send events from localscripts but you could use the other events as well with different parameters for the remote events.