PcoWSkbVqDnWTu_dm2ix
Collapse Sidebar
  1. apireference
  2. data
  3. analyticsservice

FirePlayerProgressionEvent

AnalyticsService

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.

Parameters Maximum Number of Characters
FirePlayerProgressionEvent location 5 pairs of Key and Value, each Key and Value are 50
FirePlayerProgressionEvent statistics 5 pairs of Key and Value, each Key and Value are 50
customData Variant 500 after serialized
other string types 50

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

Name Type Default Description

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”.

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

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.

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

customData

Variant

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

Returns

Return Type Summary

void

No return

Code Samples

Analytics Event - Progression

This example demonstrates how to use the AnalyticsService:FirePlayerProgressionEvent function to trigger an analytics progression event. When a player touches the parent Part, a wisdomStone, the function is fired as a LevelUp event.

local wisdomStone = script.Parent
local AnalyticsService = game:GetService(“AnalyticsService”)

wisdomStone.Touched:Connect(function (otherPart)
	local player = game.Players:GetPlayerFromCharacter(otherPart.Parent)
	if player == nil then return end
	
	local location = {
		["placeDesc"] = "Dungeon1",
		["mapDesc"] = "LeftChamberMap"
	}
	
	local statistics = {
		["amountOfExp"] = 2020,
		["amountOfGold"] = 2020,
		["kills"] = 2020
	}
	
	AnalyticsService:FirePlayerProgressionEvent(
		player,
		Enum.AnalyticsProgressionStatus.Complete, -- progressionStatus
		"LevelUp",-- category 
		location,
		statistics, -- optional
		{ AcquireType = "PickUp"}) -- customData optional
end)