AnalyticsService

The ApiKey property contains the game's PlayFab API key. It must be set and valid in order to use FireEvent. It can be set by pasting and editing the following line of code into the Command bar:

game:GetService("AnalyticsService").ApiKey = "API_KEY"

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.

See also:

• AnalyticsService:FirePlayerProgressionEvent(), triggers an event used to track player progression through the game
• AnalyticsService:FireInGameEconomyEvent(), triggers an event used to track player actions pertaining to the in-game economy
• AnalyticsService:FireLogEvent(), triggers an event used to track errors and warnings experienced by players

Parameters

Returns

local AnalyticsService = game:GetService("AnalyticsService")
local Players = game:GetService("Players")

-- server event, report a new server started
local serverInfo = {
	Time = os.time(),
	PlaceId = game.PlaceId,
}

AnalyticsService:FireCustomEvent(nil, "ServerStart", serverInfo)

Players.PlayerAdded:Connect(function(player)
	player.Chatted:Connect(function(message)
		local customData = {
			Time = os.time(),
			Message = message,
		}
		AnalyticsService:FireCustomEvent(player, "PlayerChatted", customData)
	end)
end)

FireEvent reports a custom event to PlayFab. The event is reported using a category and value, where the category is a string and the value can be a string or table. In order to use PlayFab, you must have a valid ApiKey set.

Possible Errors

• "AnalyticsService can only be executed by game server." – Tracking can only be done on the server through a Script or ModuleScript required by a script. See RunService:IsServer().
• "The ApiKey is invalid." – The ApiKey has been set, but it's invalid. Check that it is set to the correct value.
• "AnalyticsService can only accept valid UTF-8 characters." – Thrown when the value can't be serialized as UTF-8 characters. This can happen if you pass a value which has unicode characters, like emojis.
• "AnalyticsService failed in parse event value. Error: ..." – Thrown when there is an issue when serializing the provided value into a string.
• "AnalyticsService: , " and \r\n are not allowed in category." – The comma ,, the double quote ", and newline characters \r\n cannot be used in the category parameter.
• "AnalyticsService: The event value you fired is too long." – Thrown if the value parameter was too long after serialization. The length limit is 1 KB, or 1024 bytes.

Parameters

Returns

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.

See also:

• AnalyticsService:FirePlayerProgressionEvent(), triggers an event used to track player progression through the game
• AnalyticsService:FireLogEvent(), triggers an event used to track errors and warnings experienced by players
• AnalyticsService:FireCustomEvent(), triggers an event used to emit a custom event

Parameters

local location = {
    ["placeDesc"] = "Dungeon1",
    ["levelDesc"] = "level2",
    ["mapDesc"] = "LeftChamberMap",
    ["storeName"] = "DarkSmith",
    ["userDefindKey"] = "0005"
}

Returns

local AnalyticsService = game:GetService("AnalyticsService")

local gold = script.Parent

gold.Touched:Connect(function(otherPart)
	local player = game.Players:GetPlayerFromCharacter(otherPart.Parent)
	if player == nil then
		return
	end

	local location = {
		["Map"] = "someMap",
		["Position"] = tostring(gold.Position),
	}

	AnalyticsService:FireInGameEconomyEvent(
		player,
		"Sword", -- item name
		Enum.AnalyticsEconomyAction.Spend,
		"Weapon", -- itemCategory
		2020, -- amount of Gold
		"Gold", -- currency
		location,
		{ SomeCustomKey = "SomeCustomValue" }
	) -- optional customData
end)

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.

See also:

• AnalyticsService:FireInGameEconomyEvent(), triggers an event used to track player actions pertaining to the in-game economy
• AnalyticsService:FirePlayerProgressionEvent(), triggers an event used to track player progression through the game
• AnalyticsService:FireCustomEvent(), triggers an event used to emit a custom event

Parameters

local debugInfo = {
            errorCode = '123',
            stackTrace = debug.traceback()
      }

Returns

local Players = game:GetService("Players")
local TeleportService = game:GetService("TeleportService")
local AnalyticsService = game:GetService("AnalyticsService")

local placeId = game.PlaceId

local player = Players:GetPlayerByUserId(123)

xpcall(function()
	TeleportService:Teleport(placeId, player)
end, function(errorMessage)
	local debugInfo = {
		errorCode = "TeleportFailed",
		stackTrace = debug.traceback(), -- the function call stack
	}
	AnalyticsService:FireLogEvent(
		player,
		Enum.AnalyticsLogLevel.Error, -- log level
		errorMessage, -- message
		debugInfo, -- optional
		{
			PlayerId = player.UserId,
			PlaceId = placeId,
		}
	) -- customData optional
end)

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.

See also:

• AnalyticsService:FireInGameEconomyEvent(), triggers an event used to track player actions pertaining to the in-game economy
• AnalyticsService:FireLogEvent(), triggers an event used to track errors and warnings experienced by players
• AnalyticsService:FireCustomEvent(), triggers an event used to emit a custom event

Parameters

local location = {
    ["placeDesc"] = "Dungeon1",
    ["levelDesc"] = "level2",
    ["mapDesc"] = "LeftChamberMap",
    ["ProgresionType"] = "LevelUp",
    ["userDefindKey5"] = "0005"
}

local statistics = {
    ["numberOfKills"] = 111,
    ["numberOfExp"] = 222,
    ["userDefindKey3"] = number,
    ["userDefindKey4"] = number,
    ["userDefindKey5"] = number
}

Returns

local AnalyticsService = game:GetService("AnalyticsService")
local Players = game:GetService("Players")

local wisdomStone = script.Parent

wisdomStone.Touched:Connect(function(otherPart)
	local player = Players:GetPlayerFromCharacter(otherPart.Parent)
	if player == nil then
		return
	end

	local location = {
		["placeDesc"] = "Dungeon1",
		["mapDesc"] = "LeftChamberMap",
	}

	local statistics = {
		["amountOfExp"] = 1337,
		["amountOfGold"] = 1337,
		["kills"] = 1337,
	}

	AnalyticsService:FirePlayerProgressionEvent(
		player,
		Enum.AnalyticsProgressionStatus.Complete, -- progressionStatus
		"LevelUp", -- category
		location,
		statistics, -- optional
		{ AcquireType = "PickUp" }
	) -- customData optional
end)

Logs an event used to track custom metrics of a user in experience. For additional information, see Custom Events.

Parameters

Returns

local AnalyticsService = game:GetService("AnalyticsService")


-- Log when the mission starts
AnalyticsService:LogCustomEvent(
    player,
    "MissionStarted" -- Custom event name
)


-- Log when the mission is completed with the time it took
AnalyticsService:LogCustomEvent(
    player,
    "MissionCompletedDuration", -- Custom event name
    120 -- Event value used in aggregation
)

Logs an event used to track player actions related in experience.

Parameters

Returns

local AnalyticsService = game:GetService("AnalyticsService")

AnalyticsService:LogEconomyEvent(
    player,
    Enum.AnalyticsEconomyFlowType.Source,
    "Coins",
    1000, -- How many coins are in the bundle
    1020, -- balance after transaction
    Enum.AnalyticsEconomyTransactionType.IAP.Name,
    "1000CoinBundle" -- Unique identifier of the coin bundle
)

Logs an event used to track user actions stepping through a pre-planned funnel. Funnel breakdowns will only consider the user and event values from the first step in a funnel session.

Parameters

Returns

local AnalyticsService = game:GetService("AnalyticsService")
local HttpService = game:GetService("HttpService")

funnelSessionId = HttpService:GenerateGUID()

-- Log when the user opens the store
AnalyticsService:LogFunnelStepEvent(
    player,
    "ArmoryCheckout", -- Funnel name used to group steps together
    funnelSessionId, -- Funnel session id for this unique checkout session
    1, -- Step number
    "Opened Store" -- Step name
)

-- Log when the user views an item
AnalyticsService:LogFunnelStepEvent(
    player,
    "ArmoryCheckout", -- Funnel name used to group steps together
    funnelSessionId, -- Funnel session id for this unique checkout session
    2, -- Step number
    "Viewed Item" -- Step name
)

-- Log when the user views adds to cart
AnalyticsService:LogFunnelStepEvent(
    player,
    "ArmoryCheckout", -- Funnel name used to group steps together
    funnelSessionId, -- Funnel session id for this unique checkout session
    3, -- Step number
    "Added to Cart" -- Step name
)

Logs an event used to track user actions stepping through an onboarding funnel. Funnel breakdowns will only consider the user and event values from the first step in a funnel session.

Parameters

Returns

local AnalyticsService = game:GetService("AnalyticsService")

-- Log the first step of the FTUE
AnalyticsService:LogOnboardingFunnelStepEvent(
    player,
    1, -- Step number
    "Joined Game" -- Step name
)

-- Log the second step of the FTUE
AnalyticsService:LogOnboardingFunnelStepEvent(
    player,
    2, -- Step number
    "Choose Class" -- Step name
)

Logs an event for when a user has completed a level attempt. This event does not currently display in any Roblox-provided charts.

Parameters

Returns

Logs an event for when a user has started, completed, or failed a level attempt. This event does not currently display in any Roblox-provided charts.

Parameters

Returns

Logs an event for when a user has failed a level attempt. This event does not currently display in any Roblox-provided charts.

Parameters

Returns

Logs an event for when a user has started a level attempt. This event does not currently display in any Roblox-provided charts.

Parameters

Returns