Roblox UtilitiesDevlHub Roblox Documentation

Class

AnalyticsService

NotCreatableServiceNotReplicated
Inherits
Instance › Object
Memory category
Instances

Collection of methods that allows you to track how users interact with your experiences.

AnalyticsService is a collection of methods that allows you to track how users interact with your experiences, specifically player progression, in-experience economy, funnels, and custom events. For more information on using this service, see Event types.

Properties 1#

ApiKeystringPlayFab API key. Must be set in order to use FireEvent.Read: LocalUserSecurityWrite: LocalUserSecurityReadSafeDeprecated

ApiKey: string#

DeprecatedRead: LocalUserSecurityWrite: LocalUserSecurityReadSafeDeprecated

Deprecated. This property is deprecated. Do not use it for new work.

This property contains the game's PlayFab API key. It must be set and valid in order to use FireEvent.

Methods 15#

FireCustomEventFires a custom event with a custom event name and data.Deprecated
FireEventReport a custom event to PlayFab.Deprecated
FireInGameEconomyEventFire an event used to track player actions pertaining to the in-gameDeprecated
FireLogEventFire a log event used to track errors and warnings experienced by players.Deprecated
FirePlayerProgressionEventFire an event used to track player progression through the game.Deprecated
GetPlayerSegmentsAsyncReturns coarse player segment buckets for the current experience.Yields
LogCustomEventLogs an event used to track custom metrics of a user in experience.
LogEconomyEventLogs an event used to track player actions related in experience.
LogFunnelStepEventLogs an event used to track user actions stepping through a pre-planned funnel.
LogJourneyEventLogs a journey event used to track non-linear player paths through an experience.
LogOnboardingFunnelStepEventLogs an event used to track user actions stepping through an onboarding funnel.
LogProgressionCompleteEventLogs an event for when a user has completed a level attempt.
LogProgressionEventLogs an event for when a user has started, completed, or failed a level attempt.
LogProgressionFailEventLogs an event for when a user has failed a level attempt.
LogProgressionStartEventLogs an event for when a user has started a level attempt.

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

DeprecatedDeprecated

Deprecated. This deprecated function is a variant of AnalyticsService:LogCustomEvent() which should be used instead.

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

NameTypeDefaultDescription
playerInstanceThe player who triggered the custom event. nil if not player related.
eventCategorystringUser defined category. This should be the name of the event.
customDataVariantOptional. User defined data, could be a string, a number or a table.
Returns
  • ()

FireEvent(category: string, value: Variant): ()#

DeprecatedDeprecated

Deprecated. This function has been deprecated in favor of more descriptive methods, including AnalyticsService:LogCustomEvent(), AnalyticsService:LogEconomyEvent(), and AnalyticsService:LogProgressionEvent().

This function 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.

NameTypeDefaultDescription
categorystring'The category of event to report. Cannot contain the following characters: comma ,, double quote " or newline characters \r\n'.
valueVariantA value to be serialized and reported. Serialized length must not exceed 1 KiB, or 1024 bytes.
Returns
  • ()

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

DeprecatedDeprecated

Deprecated. This deprecated function is a variant of AnalyticsService:LogEconomyEvent() which should be used instead.

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.

NameTypeDefaultDescription
playerInstanceThe player who triggered the economy event.
itemNamestringThe name of the item.
economyActionAnalyticsEconomyActionIndicates the acquisition or spending of an in game resource.
itemCategorystringA user defined category for items such as "Vehicle," "Weapon.".
amountintThe amount of the currency.
currencystringThe currency used. Examples: 'gold', 'gems', 'life.'.
locationVariant

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:

Luau
local location = {
    ["placeDesc"] = "Dungeon1",
    ["levelDesc"] = "level2",
    ["mapDesc"] = "LeftChamberMap",
    ["storeName"] = "DarkSmith",
    ["userDefinedKey"] = "0005"
}
customDataVariantOptional. User defined data, could be a string, a number or a table.
Returns
  • () — No return.

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

DeprecatedDeprecated

Deprecated. This method is deprecated. Do not use it for new work.

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.

NameTypeDefaultDescription
playerInstanceThe player who triggered the error event, nil if not player related.
logLevelAnalyticsLogLevelThe specified log level (e.g. Debug, Error).
messagestringUser defined message.
debugInfoVariantOptional. 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.
customDataVariantOptional. User defined data, could be a string, a number or a table.
Returns
  • () — No return.

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

DeprecatedDeprecated

Deprecated. This deprecated function is a variant of AnalyticsService:LogProgressionEvent() which should be used instead.

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.

NameTypeDefaultDescription
playerInstanceThe player who triggered the event.
categorystringA user defined category for progression.
progressionStatusAnalyticsProgressionStatusIndicates the status of the progression.
locationVariantThe 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".
statisticsVariantOptional. 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.
customDataVariantOptional. User defined data, could be a string, a number or a table.
Returns
  • () — No return.

GetPlayerSegmentsAsync(player: Player): Dictionary#

Yields

This server-only method returns coarse segment buckets for a player in the current experience. Use these buckets at runtime to personalize content or gate features for specific player groups. If a cached result is not already available, the method may yield while the engine fetches the segment data. Successfully fetched results are cached per player for the lifetime of the server session.

If segment data is unavailable, this method does not throw. Instead, it returns HasData = false and all enum fields are set to Unknown.

This method throws only when called from the client or when the player argument is invalid.

The returned dictionary has the following structure:

Name Type Description
HasData bool Whether segment data was successfully retrieved for the player.
ActivePayerStatus Enum.ActivePayerStatus The player's current payer status bucket for this experience.
WhenUserFirstPlayed Enum.WhenUserFirstPlayed When the player first played this experience, represented as a bucket.
PlatformSpenderStatus Enum.PlayerPlatformSpenderStatus The player's platform-wide spender status bucket, including whether the player falls outside the active spender bucket.
ExperienceActivationStatus Enum.ExperienceActivationStatus Whether the player is new, active, lapsed, or reactivated in this experience, based on the last 30 days.
EngagementLevel Enum.EngagementLevel How many days the player played this experience in the last 7 days, represented as a bucket.
PlatformActivationStatus Enum.PlayerPlatformActivationStatus Whether the player is new, active, lapsed, or reactivated on Roblox, based on the last 60 days.
UserNewReturningStatus Enum.UserNewReturningStatus Whether the player is new to this experience or has played it before.
UserAcquisitionSource Enum.UserAcquisitionSource How the player first found this experience.
NameTypeDefaultDescription
playerPlayerThe player whose segment buckets should be returned.
Returns
  • Dictionary — A dictionary containing coarse player segment buckets for the current experience.

LogCustomEvent(player: Player, eventName: string, value: double = 1, customFields: Dictionary = nil): ()#

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

NameTypeDefaultDescription
playerPlayerThe user who triggered the event.
eventNamestringThe name of the custom event.
valuedouble1The value of the event that will be used in aggregation.
customFieldsDictionarynilOptional dictionary of custom fields that will provide breakdowns in Roblox-provided charts. Only specific keys, provided by AnalyticsCustomFieldKeys, will be used for these breakdowns. Limited to 8,000 unique combinations of values across the three custom fields per experience.
Returns
  • ()

LogEconomyEvent(player: Player, flowType: AnalyticsEconomyFlowType, currencyType: string, amount: float, endingBalance: float, transactionType: string, itemSku: string, customFields: Dictionary = nil): ()#

Logs an event used to track player actions related in experience. For more information, see Economy events.

NameTypeDefaultDescription
playerPlayerThe user who triggered the event.
flowTypeAnalyticsEconomyFlowTypeShould specify the direction that currency is flowing using AnalyticsEconomyFlowType.
currencyTypestringThe name of the currency being added or removed, for example "gold", "gems", or "energy". Limited to 5 unique currency types per experience.
amountfloatThe amount of currency being added or removed. This value should always be positive.
endingBalancefloatThe user's balance after the currency has been added or removed. This value should always be greater than or equal to 0.
transactionTypestringThe type of transaction that occurred. While you're free to use any transaction type, it's recommended to use the provided types from AnalyticsEconomyTransactionType such as "IAP" or "ContextualPurchase" to enable future insights from Roblox tools and charts.

Because this field type is a string, you'll need to pass the Name value of the enum. For example Enum.AnalyticsEconomyTransactionType.IAP.Name.

Limited to 20 unique types per experience.

itemSkustringOptional SKU of the item or bundle being purchased. This is a unique identifier for the item being purchased. Limited to 100 unique SKUs per experience.
customFieldsDictionarynilOptional dictionary of custom fields that will provide breakdowns in Roblox-provided charts. Only specific keys, provided by AnalyticsCustomFieldKeys, will be used for these breakdowns. Limited to 8,000 unique combinations of values across the three custom fields per experience.
Returns
  • ()

LogFunnelStepEvent(player: Player, funnelName: string, funnelSessionId: string, step: int = 1, stepName: string, customFields: Dictionary = nil): ()#

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

NameTypeDefaultDescription
playerPlayerThe user who triggered the event.
funnelNamestringThe name of the funnel. This should be the same for all steps in the funnel. Limited to 10 unique funnels per experience.
funnelSessionIdstringOptional unique identifier for the funnel session. This should be the same for all steps in the funnel.

Note that this field is only necessary for recurring funnels, for example a purchase flow funnel or an item upgrade funnel. If you don't have a natural funnel session identifier, it's recommended to use HttpService:GenerateGUID().

stepint1The step number in the funnel. This should be unique for each step in the funnel. All funnels start at step 1. Limited to steps 1-100.

Repeated steps by the same user in the same funnel session, or when funnelSessionId is nil will be ignored.

Note that if any steps are skipped, the intermediate steps will be considered completed.

stepNamestringOptional name of the step in the funnel. This field is only used for display purposes in Roblox-provided charts.
customFieldsDictionarynilOptional dictionary of custom fields that will provide breakdowns in Roblox-provided charts. Only specific keys, provided by AnalyticsCustomFieldKeys, will be used for these breakdowns. Limited to 8,000 unique combinations of values across the three custom fields per experience.
Returns
  • ()

LogJourneyEvent(player: Player, journeyName: string, nodeName: string, journeySessionId: string, customFields: Dictionary = nil): ()#

Logs a journey event used to track non-linear player paths through an experience. Unlike funnels, which track ordered sequential steps, journeys track graph-like player paths where players can move between named nodes in any order. Each call records that a player reached a specific node within a named journey. The resulting data is visualized as a Sankey diagram in Creator Hub, showing how players distribute across paths in the experience.

NameTypeDefaultDescription
playerPlayerThe player who triggered the journey event.
journeyNamestringThe name of the journey. This should be the same for all nodes in the journey. Cannot be empty and cannot contain a comma ,, double quote ", single quote ', or newline character.
nodeNamestringThe name of the node the player reached in the journey. Cannot be empty, cannot contain a comma ,, double quote ", single quote ', or newline character, and cannot start with __ (double underscore), which is reserved.
journeySessionIdstringOptional unique identifier for the journey session. This should be the same for all nodes in a single session of the journey. If provided, cannot contain a comma ,, double quote ", single quote ', or newline character.
customFieldsDictionarynilOptional dictionary of custom fields that will provide breakdowns in Roblox-provided charts. Only specific keys, provided by AnalyticsCustomFieldKeys, will be used for these breakdowns. Limited to 8,000 unique combinations of values across the three custom fields per experience.
Returns
  • ()

LogOnboardingFunnelStepEvent(player: Player, step: int, stepName: string, customFields: Dictionary = nil): ()#

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

NameTypeDefaultDescription
playerPlayerThe user who triggered the event.
stepintThe step number in the funnel. This should be unique for each step in the funnel. All funnels start at step 1. Limited to steps 1-100.

Note that if any steps are skipped, the intermediate steps will be considered completed.

stepNamestringOptional name of the step in the funnel. This field is only used for display purposes in Roblox-provided charts.
customFieldsDictionarynilOptional dictionary of custom fields that will provide breakdowns in Roblox-provided charts. Only specific keys, provided by AnalyticsCustomFieldKeys, will be used for these breakdowns. Limited to 8,000 unique combinations of values across the three custom fields per experience.
Returns
  • ()

LogProgressionCompleteEvent(player: Player, progressionPathName: string, level: int, levelName: string, customFields: Dictionary = nil): ()#

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

NameTypeDefaultDescription
playerPlayerThe player who triggered the event.
progressionPathNamestringThe name of the progression path this event belongs to, such as a world, chapter, or level group. This groups related progression events together. Cannot be empty and cannot contain a comma ,, double quote ", single quote ', or newline character.
levelintThe numeric level the player is progressing through within the progression path.
levelNamestringThe name of the level associated with this event. This field is used for display purposes in Roblox-provided charts.
customFieldsDictionarynilOptional dictionary of custom fields that will provide breakdowns in Roblox-provided charts. Only specific keys, provided by AnalyticsCustomFieldKeys, will be used for these breakdowns. Limited to 8,000 unique combinations of values across the three custom fields per experience.
Returns
  • ()

LogProgressionEvent(player: Player, progressionPathName: string, status: AnalyticsProgressionType, level: int, levelName: string, customFields: Dictionary = nil): ()#

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.

NameTypeDefaultDescription
playerPlayerThe player who triggered the event.
progressionPathNamestringThe name of the progression path this event belongs to, such as a world, chapter, or level group. This groups related progression events together. Cannot be empty and cannot contain a comma ,, double quote ", single quote ', or newline character.
statusAnalyticsProgressionTypeThe progression status to record, provided as an AnalyticsProgressionType value such as Start, Complete, or Fail. The AnalyticsService:LogProgressionStartEvent(), AnalyticsService:LogProgressionCompleteEvent(), and AnalyticsService:LogProgressionFailEvent() methods are shortcuts that set this status for you.
levelintThe numeric level the player is progressing through within the progression path.
levelNamestringThe name of the level associated with this event. This field is used for display purposes in Roblox-provided charts.
customFieldsDictionarynilOptional dictionary of custom fields that will provide breakdowns in Roblox-provided charts. Only specific keys, provided by AnalyticsCustomFieldKeys, will be used for these breakdowns. Limited to 8,000 unique combinations of values across the three custom fields per experience.
Returns
  • ()

LogProgressionFailEvent(player: Player, progressionPathName: string, level: int, levelName: string, customFields: Dictionary = nil): ()#

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

NameTypeDefaultDescription
playerPlayerThe user who triggered the event.
progressionPathNamestringThe name of the progression path this event belongs to, such as a world, chapter, or level group. This groups related progression events together. Cannot be empty and cannot contain a comma ,, double quote ", single quote ', or newline character.
levelintThe numeric level the player is progressing through within the progression path.
levelNamestringThe name of the level associated with this event. This field is used for display purposes in Roblox-provided charts.
customFieldsDictionarynilOptional dictionary of custom fields that will provide breakdowns in Roblox-provided charts. Only specific keys, provided by AnalyticsCustomFieldKeys, will be used for these breakdowns. Limited to 8,000 unique combinations of values across the three custom fields per experience.
Returns
  • ()

LogProgressionStartEvent(player: Player, progressionPathName: string, level: int, levelName: string, customFields: Dictionary = nil): ()#

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

NameTypeDefaultDescription
playerPlayerThe player who triggered the event.
progressionPathNamestringThe name of the progression path this event belongs to, such as a world, chapter, or level group. This groups related progression events together. Cannot be empty and cannot contain a comma ,, double quote ", single quote ', or newline character.
levelintThe numeric level the player is progressing through within the progression path.
levelNamestringThe name of the level associated with this event. This field is used for display purposes in Roblox-provided charts.
customFieldsDictionarynilOptional dictionary of custom fields that will provide breakdowns in Roblox-provided charts. Only specific keys, provided by AnalyticsCustomFieldKeys, will be used for these breakdowns. Limited to 8,000 unique combinations of values across the three custom fields per experience.
Returns
  • ()

Inherited members#

Inherited from Instance 58
Inherited from Object 6
Properties (2)

ClassName, className

Events (1)

Changed