@rbxts/gameanalytics

📈 GameAnalytics SDK 📊

TS typings for the GameAnalytics Roblox SDK.

• GaneAnalytics SDK repository
• GameAnalytics SDK documentation
• This package's repository

Installation

Run npm i @rbxts/gameanalytics in your project directory.

Differences between the Luau version

Unlike the normal Luau Roblox SDK, this package does not require moving scripts around in different DataModel locations.

Usage

Server side

In a server script, run GameAnalytics.initialize

import { GameAnalytics } from "@rbxts/gameanalytics";

GameAnalytics.initialize({
	gameKey: "<GAME KEY HERE>",
	secretKey: "<SECRET KEY HERE>",
	availableResourceCurrencies = ["Coins"],
	...
});

or initializeServer, which uses a predefined configuration:

import { initializeServer } from "@rbxts/gameanalytics";

initializeServer("<GAME KEY HERE>", "<SECRET KEY HERE>");

Predefined configuration values

{
	build: "0.1",

	enableInfoLog: true,
	enableVerboseLog: true,

	// debug is enabled in Studio by default
	enableDebugLog: undefined,

	automaticSendBusinessEvents: true,
	reportErrors: true,

	availableCustomDimensions01: [],
	availableCustomDimensions02: [],
	availableCustomDimensions03: [],
	availableResourceCurrencies: [],
	availableResourceItemTypes: [],
	availableGamepasses: []
}

After initialization, you can now fire analytics events, such as GameAnalytics.addDesignEvent, GameAnalytics.addProgressionEvent, GameAnalytics.addResourceEvent. It's strongly recommended that you read the Event Tracking guide for the usage of these functions.

Client side

In a client script, run initializeClient:

import { initializeClient } from "@rbxts/gameanalytics";

initializeClient();

Warning

Retrieving data from the server on the client side (A/B experiment data, Remote Configs), is not implemented in the GameAnalytics SDK. If you want to use one of these features on the client side, you will have to create RemoteEvents manually.

Custom User Ids

For custom usernames, implementing this such as in the guide (on the client side) is not recommended for security reasons.

Instead, when using GameAnalytics User Ids (such as with event tracking functions) it's simpler to pass a Player's UserId to a function to retrieve their custom username

const getUsername = (player: Player) => {
  // don't actually use DisplayNames
  return player.DisplayName;
};

GameAnalytics.addDesignEvent(getUsername(player), {
  eventId: "testEvent",
});

---

If you would like to contribute to the GameAnalytics Roblox SDK, please file Pull Requests and Issues in its GitHub repository, and not in the repository of this package. The types here will reflect the most recent release of the Luau code.