AnalyticsService

Show Deprecated
Service
Deprecated

Note This service should only be used by developers who are enrolled in the PlayFab program.

The AnalyticsService provides developers with out-of-the-box analytics so they can improve their games.

Developers can report events and see visual analysis results on PlayFab webpage. For more information on how to enroll in the PlayFab Program, take a look at this DevForum post.

Summary

Properties

Events

Methods

FireCustomEvent(player: Instance, eventCategory: string, customData: Variant): void  

Fires a custom event with a custom event name and data.

FireInGameEconomyEvent(player: Instance, itemName: string, economyAction: AnalyticsEconomyAction, itemCategory: string, amount: number, currency: string, location: Variant, customData: Variant): void  

Fire an event used to track player actions pertaining to the in-game economy.

FireLogEvent(player: Instance, logLevel: AnalyticsLogLevel, message: string, debugInfo: Variant, customData: Variant): void  

Fire a log event used to track errors and warnings experienced by players.

FirePlayerProgressionEvent(player: Instance, category: string, progressionStatus: AnalyticsProgressionStatus, location: Variant, statistics: Variant, customData: Variant): void  

Fire an event used to track player progression through the game.

Properties

Events

Methods

FireCustomEvent

void

This function triggers a custom event with a custom event name data.

Limits of events

Each game server is allowed a certain number of standard events API calls based on the number of players present (more players means more events will be needed). The events that exceed the limit will be dropped and log an error to the developer console. - Per minute limit: 120 + numPlayers * 20, all events shared this limit. - Cooldown: refresh every 10 seconds

Limits of parameters

Limit the size of parameters. The event that exceeds the limit will be dropped and log an error to the developer console.

ParametersMaximum Number of Characters
customData Variant500 after serialized
other string types50

See also:

Parameters

player: Instance

The player who triggered the custom event. nil if not player related.

eventCategory: string

User defined category. This should be the name of the event.

customData: Variant

Optional. User defined data, could be a string, a number or a table.


Returns

void

No return.

Code Samples

Analytics Event - Custom

1local AnalyticsService = game:GetService("AnalyticsService")
2local Players = game:GetService("Players")
3
4-- server event, report a new server started
5local serverInfo = {
6 Time = os.time(),
7 PlaceId = game.PlaceId,
8}
9
10AnalyticsService:FireCustomEvent(nil, "ServerStart", serverInfo)
11
12Players.PlayerAdded:Connect(function(player)
13 player.Chatted:Connect(function(message)
14 local customData = {
15 Time = os.time(),
16 Message = message,
17 }
18 AnalyticsService:FireCustomEvent(player, "PlayerChatted", customData)
19 end)
20end)

FireInGameEconomyEvent

void

This function triggers an event used to track player actions pertaining to the in-game economy.

For example, it should be called to track when players acquire or spend virtual items within the economy like currency.

Limits of events

Each game server is allowed a certain number of standard events API calls based on the number of players present (more players means more events will be needed). The events that exceed the limit will be dropped and log an error to the developer console. - Per minute limit: 120 + numPlayers * 20, all events shared this limit. - Cooldown: refresh every 10 seconds

Limits of parameters

Limit the size of parameters. The event that exceeds the limit will be dropped and log an error to the developer console.

ParametersMaximum Number of Characters
customData Variant500 after serialized
other string types50

See also:

Parameters

player: Instance

The player who triggered the economy event.

itemName: string

The name of the item.

economyAction: AnalyticsEconomyAction

Indicates the acquisition or spending of an in game resource.

itemCategory: string

A user defined category for items such as "Vehicle," "Weapon.".

amount: number

The amount of the currency.

currency: string

The currency used. Examples: 'gold', 'gems', 'life.'.

location: Variant

The event location. A dictionary that each key-value represents an entry of location data. The key-value is a string-string pair. With this you can query which are the most popular "stores" then maybe you want to increase/lower the price for the stores.

See the example below:


1local location = {
2 ["placeDesc"] = "Dungeon1",
3 ["levelDesc"] = "level2",
4 ["mapDesc"] = "LeftChamberMap",
5 ["storeName"] = "DarkSmith",
6 ["userDefindKey"] = "0005"
7}
8
customData: Variant

Optional. User defined data, could be a string, a number or a table.


Returns

void

No return.

Code Samples

Analytics Event - Economy

1local AnalyticsService = game:GetService("AnalyticsService")
2
3local gold = script.Parent
4
5gold.Touched:Connect(function(otherPart)
6 local player = game.Players:GetPlayerFromCharacter(otherPart.Parent)
7 if player == nil then
8 return
9 end
10
11 local location = {
12 ["Map"] = "someMap",
13 ["Position"] = tostring(gold.Position),
14 }
15
16 AnalyticsService:FireInGameEconomyEvent(
17 player,
18 "Sword", -- item name
19 Enum.AnalyticsEconomyAction.Spend,
20 "Weapon", -- itemCategory
21 2020, -- amount of Gold
22 "Gold", -- currency
23 location,
24 { SomeCustomKey = "SomeCustomValue" }
25 ) -- optional customData
26end)

FireLogEvent

void

This function triggers an event used to track errors and warnings experienced by players.

For example, it could be called to indicate when a function call fails - such as a datastore save or TeleportService:Teleport(). See the example below.

Limits of events

Each game server is allowed a certain number of standard events API calls based on the number of players present (more players means more events will be needed). The events that exceed the limit will be dropped and log an error to the developer console. - Per minute limit: 120 + numPlayers * 20, all events shared this limit. - Cooldown: refresh every 10 seconds

Limits of parameters

Limit the size of parameters. The event that exceeds the limit will be dropped and log an error to the developer console.

ParametersMaximum Number of Characters
FireLogEvent stackTrace1000
FireLogEvent message500
customData Variant500 after serialized
other string types50

See also:

Parameters

player: Instance

The player who triggered the error event, nil if not player related.

The specified log level (e.g. Debug, Error).

message: string

User defined message.

debugInfo: Variant

Optional. A dictionary which contains predefined keys including "errorCode" and "stackTrace". Both keys values are strings. stackTrace is a traceback of the current function call stack.


1local debugInfo = {
2 errorCode = '123',
3 stackTrace = debug.traceback()
4 }
5
customData: Variant

Optional. User defined data, could be a string, a number or a table.


Returns

void

No return.

Code Samples

Analytics Event - Log

1local Players = game:GetService("Players")
2local TeleportService = game:GetService("TeleportService")
3local AnalyticsService = game:GetService("AnalyticsService")
4
5local placeId = game.PlaceId
6
7local player = Players:GetPlayerByUserId(123)
8
9xpcall(function()
10 TeleportService:Teleport(placeId, player)
11end, function(errorMessage)
12 local debugInfo = {
13 errorCode = "TeleportFailed",
14 stackTrace = debug.traceback(), -- the function call stack
15 }
16 AnalyticsService:FireLogEvent(
17 player,
18 Enum.AnalyticsLogLevel.Error, -- log level
19 errorMessage, -- message
20 debugInfo, -- optional
21 {
22 PlayerId = player.UserId,
23 PlaceId = placeId,
24 }
25 ) -- customData optional
26end)

FirePlayerProgressionEvent

void

This function triggers an event used to track player progression through the game.

For example, it should be called when a player starts an in-game tutorial and again that player finishes the tutorial. Another example (see below) includes tracking when a player gains experience, collects objects, and levels up.

Limits of events

Each game server is allowed a certain number of standard events API calls based on the number of players present (more players means more events will be needed). The events that exceed the limit will be dropped and log an error to the developer console. - Per minute limit: 120 + numPlayers * 20, all events shared this limit. - Cooldown: refresh every 10 seconds

Limits of parameters

Limit the size of parameters. The event that exceeds the limit will be dropped and log an error to the developer console.

ParametersMaximum Number of Characters
FirePlayerProgressionEvent location5 pairs of Key and Value, each Key and Value are 50
FirePlayerProgressionEvent statistics5 pairs of Key and Value, each Key and Value are 50
customData Variant500 after serialized
other string types50

See also:

Parameters

player: Instance

The player who triggered the event.

category: string

A user defined category for progression.

progressionStatus: AnalyticsProgressionStatus

Indicates the status of the progression.

location: Variant

The event location. A dictionary that each key-value represents an entry of location data. The key-value is a string-string pair. With this developers can query where is the most frequent location for a specific progression event category. For example, the category could be "LevelUp".


1local location = {
2 ["placeDesc"] = "Dungeon1",
3 ["levelDesc"] = "level2",
4 ["mapDesc"] = "LeftChamberMap",
5 ["ProgresionType"] = "LevelUp",
6 ["userDefindKey5"] = "0005"
7}
8
statistics: Variant

Optional. A dictionary that each key-value represents an entry of statistics data that allows developers to track any specific data that they want to collect as players progress through their game. Key-Value is a string-number pair.


1local statistics = {
2 ["numberOfKills"] = 111,
3 ["numberOfExp"] = 222,
4 ["userDefindKey3"] = number,
5 ["userDefindKey4"] = number,
6 ["userDefindKey5"] = number
7}
8
customData: Variant

Optional. User defined data, could be a string, a number or a table.


Returns

void

No return.

Code Samples

Analytics Event - Progression

1local AnalyticsService = game:GetService("AnalyticsService")
2local Players = game:GetService("Players")
3
4local wisdomStone = script.Parent
5
6wisdomStone.Touched:Connect(function(otherPart)
7 local player = Players:GetPlayerFromCharacter(otherPart.Parent)
8 if player == nil then
9 return
10 end
11
12 local location = {
13 ["placeDesc"] = "Dungeon1",
14 ["mapDesc"] = "LeftChamberMap",
15 }
16
17 local statistics = {
18 ["amountOfExp"] = 1337,
19 ["amountOfGold"] = 1337,
20 ["kills"] = 1337,
21 }
22
23 AnalyticsService:FirePlayerProgressionEvent(
24 player,
25 Enum.AnalyticsProgressionStatus.Complete, -- progressionStatus
26 "LevelUp", -- category
27 location,
28 statistics, -- optional
29 { AcquireType = "PickUp" }
30 ) -- customData optional
31end)