Class
AnalyticsService
NotCreatableServiceNotReplicated
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#
Methods 15#
| FireCustomEvent | Fires a custom event with a custom event name and data.Deprecated |
| FireEvent | Report a custom event to PlayFab.Deprecated |
| FireInGameEconomyEvent | Fire an event used to track player actions pertaining to the in-gameDeprecated |
| FireLogEvent | Fire a log event used to track errors and warnings experienced by players.Deprecated |
| FirePlayerProgressionEvent | Fire an event used to track player progression through the game.Deprecated |
| GetPlayerSegmentsAsync | Returns coarse player segment buckets for the current experience.Yields |
| LogCustomEvent | Logs an event used to track custom metrics of a user in experience. |
| LogEconomyEvent | Logs an event used to track player actions related in experience. |
| LogFunnelStepEvent | Logs an event used to track user actions stepping through a pre-planned funnel. |
| LogJourneyEvent | Logs a journey event used to track non-linear player paths through an experience. |
| LogOnboardingFunnelStepEvent | Logs an event used to track user actions stepping through an onboarding funnel. |
| LogProgressionCompleteEvent | Logs an event for when a user has completed a level attempt. |
| LogProgressionEvent | Logs an event for when a user has started, completed, or failed a level attempt. |
| LogProgressionFailEvent | Logs an event for when a user has failed a level attempt. |
| LogProgressionStartEvent | Logs 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.
| Name | Type | Default | Description |
|---|---|---|---|
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
()
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.
| Name | Type | Default | Description |
|---|---|---|---|
category | string | 'The category of event to report. Cannot contain the following
characters: comma ,, double quote " or newline characters \r\n'. | |
value | Variant | A 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.
| Name | Type | Default | Description |
|---|---|---|---|
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 | int | 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: | |
customData | Variant | Optional. 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.
| Name | Type | Default | Description |
|---|---|---|---|
player | Instance | The player who triggered the error event, nil if not player related. | |
logLevel | AnalyticsLogLevel | 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. | |
customData | Variant | Optional. 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.
| 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". | |
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. | |
customData | Variant | Optional. 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. |
| Name | Type | Default | Description |
|---|---|---|---|
player | Player | The 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.
| Name | Type | Default | Description |
|---|---|---|---|
player | Player | The user who triggered the event. | |
eventName | string | The name of the custom event. | |
value | double | 1 | The value of the event that will be used in aggregation. |
customFields | Dictionary | nil | Optional 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.
| Name | Type | Default | Description |
|---|---|---|---|
player | Player | The user who triggered the event. | |
flowType | AnalyticsEconomyFlowType | Should specify the direction that currency is flowing using
AnalyticsEconomyFlowType. | |
currencyType | string | The name of the currency being added or removed, for example "gold",
"gems", or "energy". Limited to 5 unique currency types per
experience. | |
amount | float | The amount of currency being added or removed. This value should always be positive. | |
endingBalance | float | The user's balance after the currency has been added or removed. This
value should always be greater than or equal to 0. | |
transactionType | string | The 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 Limited to 20 unique types per experience. | |
itemSku | string | Optional 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. | |
customFields | Dictionary | nil | Optional 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.
| Name | Type | Default | Description |
|---|---|---|---|
player | Player | The user who triggered the event. | |
funnelName | string | The name of the funnel. This should be the same for all steps in the funnel. Limited to 10 unique funnels per experience. | |
funnelSessionId | string | Optional 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
| |
step | int | 1 | The 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
Note that if any steps are skipped, the intermediate steps will be considered completed. |
stepName | string | Optional name of the step in the funnel. This field is only used for display purposes in Roblox-provided charts. | |
customFields | Dictionary | nil | Optional 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.
| Name | Type | Default | Description |
|---|---|---|---|
player | Player | The player who triggered the journey event. | |
journeyName | string | The 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. | |
nodeName | string | The 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. | |
journeySessionId | string | Optional 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. | |
customFields | Dictionary | nil | Optional 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.
| Name | Type | Default | Description |
|---|---|---|---|
player | Player | The user who triggered the event. | |
step | int | The 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. | |
stepName | string | Optional name of the step in the funnel. This field is only used for display purposes in Roblox-provided charts. | |
customFields | Dictionary | nil | Optional 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.
| Name | Type | Default | Description |
|---|---|---|---|
player | Player | The player who triggered the event. | |
progressionPathName | string | The 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. | |
level | int | The numeric level the player is progressing through within the progression path. | |
levelName | string | The name of the level associated with this event. This field is used for display purposes in Roblox-provided charts. | |
customFields | Dictionary | nil | Optional 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.
| Name | Type | Default | Description |
|---|---|---|---|
player | Player | The player who triggered the event. | |
progressionPathName | string | The 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. | |
status | AnalyticsProgressionType | The 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. | |
level | int | The numeric level the player is progressing through within the progression path. | |
levelName | string | The name of the level associated with this event. This field is used for display purposes in Roblox-provided charts. | |
customFields | Dictionary | nil | Optional 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.
| Name | Type | Default | Description |
|---|---|---|---|
player | Player | The user who triggered the event. | |
progressionPathName | string | The 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. | |
level | int | The numeric level the player is progressing through within the progression path. | |
levelName | string | The name of the level associated with this event. This field is used for display purposes in Roblox-provided charts. | |
customFields | Dictionary | nil | Optional 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.
| Name | Type | Default | Description |
|---|---|---|---|
player | Player | The player who triggered the event. | |
progressionPathName | string | The 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. | |
level | int | The numeric level the player is progressing through within the progression path. | |
levelName | string | The name of the level associated with this event. This field is used for display purposes in Roblox-provided charts. | |
customFields | Dictionary | nil | Optional 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
Properties (10)
Archivable, archivable, Capabilities, IsInSandbox, Name, Parent, PredictionMode, RobloxLocked, Sandboxed, UniqueId
Methods (39)
AddTag, children, ClearAllChildren, Clone, clone, Destroy, destroy, FindFirstAncestor, FindFirstAncestorOfClass, FindFirstAncestorWhichIsA, FindFirstChild, findFirstChild, FindFirstChildOfClass, FindFirstChildWhichIsA, FindFirstDescendant, GetActor, GetAttribute, GetAttributeChangedSignal, GetAttributes, GetChildren, getChildren, GetDebugId, GetDescendants, GetFullName, GetStyled, GetStyledPropertyChangedSignal, GetTags, HasTag, IsAncestorOf, IsDescendantOf, isDescendantOf, IsPropertyModified, QueryDescendants, Remove, remove, RemoveTag, ResetPropertyToDefault, SetAttribute, WaitForChild