Skip to main content

Setup

Download the SDK​

You can download the latest version of the Roblox SDK from GitHub (using Rojo) or directly from Roblox

Rojo​

To install, please clone github repo or download .zip from github file and use rojo to sync files into Roblox Studio. For more info on how to use Rojo read here.

Wally​

To use wally, run the following command:

wally install gameanalytics

Roblox module​

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 ReplicatedStorage
  2. Move the Server script under ServerScriptService (optional, not needed if you want to programmatically initialize the SDK from your own script)
  3. Move the Client script under StarterPlayer/StarerPlayerScripts

Initialization​

caution

In order to be able to send events using GameAnalytics, you'll first have to enable HTTP requests in RobloxStudio. Please check out the official Roblox documentation here on how to enable HTTP requests in your project.

Init the SDK​

Now we should be ready for adding code to activate the SDK.

There are 2 phases you need to get started:

  • Configuration
  • Initialization

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​

The configuration phase happens before initialization is called. The available configuration options are listed here:

  • build
  • custom user id
  • 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] (e.g 1.0.0)

GameAnalytics:configureBuild("0.1.0")

Custom user id​

You can create a function (on client side) to use to create a custom user id for each user. Here is an example of a local function for custom user id:

local player = game.Players.LocalPlayer

local function getCustomUserId()
    return player.DisplayName
end

To enable custom user id you need to add this argument to when initializing the SDK:

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

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.

caution

A maximum of 20 values are allowed for each list.

danger

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.

GameAnalytics:configureAvailableCustomDimensions01({"ninja", "samurai"})
GameAnalytics:configureAvailableCustomDimensions02({"whale", "dolphin"})
GameAnalytics:configureAvailableCustomDimensions03({"horde", "alliance"})
GameAnalytics:configureAvailableResourceCurrencies({"gold", "gems"})
GameAnalytics:configureAvailableResourceItemTypes({"weapons", "food"})
GameAnalytics:configureAvailableGamepasses({"mygamepass"})

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

local ReplicationStorage = game:GetService("ReplicationStorage")
-- using wally package
-- local GameAnalytics = require(ReplicationStorage.Packages.GameAnalytics)
-- using rojo or manually copied in
local GameAnalytics = require(ReplicationStorage.GameAnalytics)

Enable/disable event submission​

If you for GDPR purposes need to disable event submission you can call the following:

GameAnalytics:setEnabledEventSubmission(false)

By default event submission is of course enabled. You will still receive configs if you have set any for your game even after disabling event submission.

Initializing the SDK​

In order to initialize the SDK you will have to call this from your script:

GameAnalytics:initServer("[YOUR_GAME_KEY]", "[YOUR_SECRET_KEY]")

On player ready event​

To listen to when a player is ready meaning they have gotten their player data loaded for them.

Create something like the below in another server script:

local OnPlayerReadyEvent
OnPlayerReadyEvent = OnPlayerReadyEvent or game:GetService("ReplicatedStorage"):WaitForChild("OnPlayerReadyEvent")

local function onPlayerReady(Player)
    --Do stuff in here
end

OnPlayerReadyEvent.Event:connect(onPlayerReady)

It is also possible to call this function to ask if a player is ready:

local isPlayerReady = GameAnalytics:isPlayerReady(playerId)