GameAnalyticsHandler

A class that allows you to easily track events, resources, and progressions in your game using GameAnalytics.

Types

GameAnalyticsPlayerIdentifier

</>

type GameAnalyticsPlayerIdentifier = Player | Model | number | string | nil

Player to track the event for. (Player, Character, userId, Username, nil)

If it is nil, it will be treated as the "Game / Server"

GameAnalyticsProgressionStatus

</>

type GameAnalyticsProgressionStatus = "Start" | "Complete" | "Fail"

Enum for progression status required for ProgressionEvents

Functions

new

static

</>

GameAnalyticsHandler.new(Params: {

BuildVersion: string,

Resources: {string},

Currencies: {string},

GameKey: string,

SecretKey: string,

AutomaticSendBusinessEvents: boolean?,

TrackPerformance: boolean?,

EnabledInfoLog: boolean?,

EnabledVerboseLog: boolean?,

EnabledReportErrors: boolean?,

SuppressWarnings: boolean?,

SendEventsToGAFromStudio: boolean?,

SendEventsPredicate: (() → boolean)?

}) → ()

The constructor for the GameAnalyticsHandler. Creates a new instance of the GameAnalyticsHandler where you can track events, resources, and progressions in your game using GameAnalytics.

[REQUIRED]

• BuildVersion -> The version of the game. Example: "0.0.1"
• Resources -> The resources to track in the game. Example: {"Wheel Spin", "Chest", "Daily Rewards"}
• Currencies -> The currencies to track in the game. Example: {"Coins", "Gems", "Diamonds"}
• GameKey -> The Game Key provided by GameAnalytics.
• SecretKey -> The Secret Key provided by GameAnalytics.

[OPTIONAL]

• AutomaticSendBusinessEvents -> Automatically send business events to GameAnalytics. Default: true
• TrackPerformance -> Track performance of the server and clients. Default: true
• EnabledInfoLog -> Enable info logs. Default: true
• EnabledVerboseLog -> Enable verbose logs. Default: true
• EnabledReportErrors -> Enable error reporting. Default: true
• SuppressWarnings -> Suppress warnings. Default: false
• SendEventsToGAFromStudio -> Send events to GameAnalytics from studio. Default: false
• SendEventsPredicate -> A predicate function to determine if events should be sent to GameAnalytics. Default: (()-> true)

Example Usage

local gaParams = {
    BuildVersion = "0.0.1",
    Resources = {"Wheel Spin", "Chest", "Daily Rewards"},
    Currencies = {"Coins", "Gems", "Diamonds"},
    GameKey = ServerStorage.GameAnalyticsSettings.GameKey.Value,
    SecretKey = ServerStorage.GameAnalyticsSettings.SecretKey.Value,
}

local gaClass = GameAnalyticsHandler.new(gaParams)

AddDesignEvent

</>

GameAnalyticsHandler:AddDesignEvent(designParams: {

identifier: GameAnalyticsPlayerIdentifier?,

eventId: string,

value: number

}) → ()

Design Events are used to track player interactions in the game. They are custom events that allow tracking different actions or behaviors within a game. These events can be used to monitor game mechanics and understand player behavior in a detailed way. The eventId is a unique identifier used to categorize and track specific design events. It is formatted as "Label1:Label2:Label3:Label4:Label5" to provide structured and hiearchical way of organizing these events.

• identifier -> The player to track the event for.
• eventId -> The event id to track. Example: "Killed:Nuketown:MP5" Tracking Killed event on what map with what gun
• value -> The value to track for the event. Example: 1 for "Killed:Nuketown:MP5" would be 1 kill.

EventId category limits

EventIds can have at max 5 labels (categories), and at minimum 1 label. Ex: "Label1:Label2:Label3:Label4:Label5"

Example Usage

-- Tracking how many kills a player got with which gun and on which map.
local playerKills: {[Player]: number} = {}

-- increment players kills, and report the event to GameAnalytics.
local function plrGotKill(player: Player, playerWhoGotKilled: Player, mapName: string, gunName: string)
    if not playerKills[player] then
        playerKills[player] = 0
    end

    playerKills[player] += 1

    gaClass:AddDesignEvent({
        identifier = player,
        eventId = `Killed:{mapName}:{gunName}`,
        value = 1
    })
end

plrGotKill(game.Players.KinqAndi, game.Players.builderman, "Nuketown", "MP5")

AddResourceEvent

</>

GameAnalyticsHandler:AddResourceEvent(resourceParams: {

identifier: GameAnalyticsPlayerIdentifier,

currencyName: string,

before: number,

after: number,

itemType: string,

itemId: string

}) → ()

Resource Events are used to track the flow of resources in the game such as currency. These events can be used to monitor the economy of the game and understand how players interact with the resources in the game. Helping understand how players acquire and spend their in-game resources.

• identifier -> The player to track the event for.
• currencyName -> The currency name to track. Example: "Coins"
• before -> The amount of currency before the event. Example 200
• after -> The amount of currency after the event. Example 100
• itemType -> The itemType of the resource. Example: "Chest"
• itemId -> The itemId of the resource. There are no restrictions on this field. Example: "Gold"

Field Restrictions

The 'currencyName' parameter must be defined in the class constructor Params as an item of Currencies. The 'itemType' parameter must be defined in the class constructor Params as an item of Resources.

Example Usage

-- In this example, we are tracking the player's resource event. The player had 200 coins before and 50 coins after buying a gold chest.
local playersCoins: {[Player]: number} = {}

--increments the player's amount of a specific currency
local function incrementCurrency(player: Player, currencyName: string, currencyAmount: number, itemType: string, itemId: string)
    if not playersCoins[player] then
        playersCoins[player] = 200
    end

    local beforeIncrement: number =  playersCoins[player]
    local afterIncrement: number = beforeIncrement + currencyAmount

    playersCoins[player] = afterIncrement

    gaClass:AddResourceEvent({
        identifier = player,
        currencyName = currencyName,
        before = beforeIncrement,
        after = afterIncrement,
        itemType = itemType,
        itemId = itemId
    })
end

--decrements the player's amount of a specific currency
local function decrementCurrency(player: Player, currencyName: string, currencyAmount: number)
    incrementCurrency(player, currencyName, -currencyAmount)
end

--opens a chest
local chestCosts = {["Gold"] = 150, ["Silver"] = 25, ["Bronze"] = 10}

--open a chest up for player
local function openChest(player: Player, chestId: string)
    if playersCoins[player] and playersCoins[player] > chestCosts[chestId] then
        decrementCurrency(player, "Coins", -chestCosts[chestId], "Chest", chestId)

        -- grant rewards
    end
end

AddProgressionEvent

</>

GameAnalyticsHandler:AddProgressionEvent(progressionParams: {

identifier: GameAnalyticsPlayerIdentifier,

progressionStatus: GameAnalyticsProgressionStatus,

progression01: string,

progression02: string?,

progression03: string?,

score: number

}) → ()

Progression events are used to track player's progress through different stages, levels, or milestones within a game. These events help understand how players are advancing, where they might be getting stuck, and how they are interacting with the game's progression system.

• identifier -> The player to track the event for.
• progressionStatus -> GameAnalyticsProgressionStatus enum values. ("Start", "Complete", "Fail").
• progression01 -> Defines the category of the progression. Example: "World1"
• progression02 -> Defines the sub-category of the progression. Example: "WeaponLeveled"
• progression03 -> Defines the sub-sub-category of the progressio. Example: "Sword3"
• score -> Defines the score of the progression. Example: 10

info

Out of the keys (progression01, progression02, progression03), only progression01 is required.

Example Usage

local playerWeapons: {[Player]: {
    [string]: {[string]: number}
}} = {}

--tracks the player's weapon level progression
local function levelWeapon(player: Player, worldName: string, weaponName: string, level: number)
    -- handle table defaults
    playerWeapons[player] = playerWeapons[player] or {}
    playerWeapons[player][worldName] = playerWeapons[player][worldName] or {}
    playerWeapons[player][worldName][weaponName] = playerWeapons[player][worldName][weaponName] or 1


    local previousLevel: number = playerWeapons[player][worldName][weaponName]
    playerWeapons[player][worldName][weaponName] = level

    gaClass:AddProgressionEvent({
        identifier = player,
        progressionStatus = "Complete",
        progression01 = "WeaponLeveled",
        progression02 = worldName,
        progression03 = weaponName,
        score = level
    })
end

-- In this example, we are tracking the player's progression in the game. The player has leveled Sword3 to 10 in World1.
levelWeapon(game.Players.KinqAndi, "Nuketown", "MP5", 5)

ProcessReceiptCallback

</>

GameAnalyticsHandler:ProcessReceiptCallback(info: {

PurchaseId: number,

PlayerId: number,

ProductId: number,

PlaceIdWherePurchased: number,

CurrencySpent: number,

CurrencyType: Enum.CurrencyType

}) → ()

Reporting a purchase event to GameAnalytics. This is used to track developer product purchases made in the game.

info

The info parameter should be the receiptInfo provided by MarketplaceService.ProcessReceipt.

Example Usage

MarketplaceService.ProcessReceipt = function(receiptInfo)
    gaClass:ProcessReceiptCallback(receiptInfo)
    --grant developer product rewards
end

GetDefaultSetting

</>

GameAnalyticsHandler:GetDefaultSetting(settingName: string) → any

Get a default setting of the constructor parameters.

Example Usage

local automaticSendBusinessEvents = gaClass:GetDefaultSetting("AutomaticSendBusinessEvents")
print(automaticSendBusinessEvents) -- true

Destroy

</>

GameAnalyticsHandler:Destroy() → ()

Destroys the game analytics class and clears all connections.