Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Analytics

Overview

Use AnalyticsService to log what players do in your world as events and check the aggregated results in Creator Hub after publishing.

You can find out how far players progress through the tutorial and how often they perform certain actions, which helps you find where players drop off and improve your world.

Components

Type
Description

Custom Event

A one-off event whose name and value are defined by the creator.

Log it at the moment a specific action happens, such as collecting a coin, clearing a mission, or entering a shop.

Onboarding Funnel Event

An event that logs players' tutorial (onboarding) progress.

The number of players who reach each step is aggregated, so you can see at which step many players drop off.

Custom Field

A breakdown value used to view events by detailed conditions. Up to 3 can be specified per event.

How to Use

Getting the Service

Get AnalyticsService with GetService(). The event logging functions can be called only from a server script.

local AnalyticsService = game:GetService("AnalyticsService")
Function
Description

LogCustomEvent(player, eventName, value(*optional), customFields(*optional))

Logs one Custom Event

LogOnboardingFunnelStepEvent(player, step, stepName(*optional), customFields(*optional))

Logs that a player reached a step of the onboarding funnel

Neither function returns a value, and both return immediately without waiting for the events to be sent.

The parameters and behavior of each function can also be found on the page below.

AnalyticsService

Logging a Custom Event

Parameter
Description

player

The Player who triggered the event

eventName

The name of the event. An empty string cannot be used, and up to 50 characters are saved.

value

(Optional) A number logged with the event. Negative numbers and decimals can be used, but NaN and infinity cannot.

customFields

(Optional) A Custom Field table used to break down the event

An event logged without value and an event logged with a value of 0 are saved as different values. If omitted, the event is logged without a value; if 0 is passed, the event is logged with a value of 0.

It is recommended to omit value for events where only the number of occurrences matters, and to pass value only for events where the value itself is meaningful, such as clear time or the amount collected.

Logging Onboarding Funnel Steps

Parameter
Description

player

The Player who progressed through the step

step

The step number. Use a number from 1 to 100, with up to two decimal places.

stepName

(Optional) The step name shown in Creator Hub. Up to 50 characters are saved.

customFields

(Optional) A Custom Field table used to break down the step

To count joining the world as step 1, log step 1 in the PlayerAdded event.

Numbering Steps

It is recommended to number steps in order of progress, starting from 1.

To add a new step between steps of a funnel that has already been published, you can use a decimal. For example, you can add step 2.5 between step 2 and step 3.

It is recommended not to use values with three or more decimal places. A calculated value is rounded to two decimal places before it is passed.

How Steps Are Aggregated

  • Even if the same player logs the same step multiple times, only the first time the step is reached is reflected in the step conversion rate.

  • If a higher step is logged without logging the steps in between, the earlier steps are also counted as completed.

  • If a new step is added between existing steps, players who have already reached the next step are also counted as having completed the new step. Players before and after the step was added are not distinguished.

  • Calls that log the same step repeatedly still count toward the call limit.

Breaking Down with Custom Fields

With Custom Fields, you can compare the same event by conditions such as map, difficulty, or how an item was obtained.

Key
Description

Enum.AnalyticsCustomFieldKeys.CustomField01

The first breakdown value

Enum.AnalyticsCustomFieldKeys.CustomField02

The second breakdown value

Enum.AnalyticsCustomFieldKeys.CustomField03

The third breakdown value

  • Use the Name of the Enum item as the key.

  • Only strings can be used as values. To use a number as a breakdown value, convert it with tostring() before passing it.

  • Undefined keys are ignored.

  • Up to 50 characters of each value are saved.

Logging Actions That Happen on the Client

For actions that happen on the client, such as clicking a UI button, notify the server with a RemoteEvent and log the event in a server script.

In this case, it is recommended to decide the step number or event value on the server. If the value sent by the client is logged as is, unintended values may be aggregated.

LocalScript

Script

For more information about RemoteEvent, refer to the page below.

Server-Client Communication

String Length

Up to 50 characters of eventName, stepName, and each Custom Field value are saved, and anything beyond 50 characters is cut off before saving.

Each letter, digit, or Korean character counts as 1, and most emojis count as 2 or more. If an emoji falls on the 50th character, the event may not be saved, so it is recommended not to use emojis in names.

Full Code Example

The following code logs step 1 when a player joins, steps 2~3 when the player reaches a checkpoint, and step 4 when the player closes the guide UI. When a coin is collected in the tutorial area, a Custom Event is logged as well.

Create a TutorialCheckpoints folder in Workspace, place Parts named after each step inside it, and set the step number of each Part with a FunnelStep Attribute (number). Add a C2S_GuideClosed RemoteEvent to ReplicatedStorage.

Script (ServerScriptService)

LocalScript (StarterPlayerScripts)

  • LogFunnelStep(player, step, stepName) / LogCustom(player, eventName, value, area)

    • Calls the logging function wrapped in pcall()

    • Game logic keeps running even if an invalid value is passed, and the cause is printed to the Output

  • OnPlayerAdded(player)

    • Logs step 1 when a player joins

  • ConnectCheckpoint(checkpoint)

    • Logs the step with the Part's FunnelStep Attribute and name when the player touches a checkpoint Part

    • Because Touched can fire several times for a single touch, the steps already logged for each player are stored in LoggedSteps so that each step is logged only once

    • Because step numbers are managed with Attributes, the script does not need to be modified when steps are added or changed

  • OnGuideClosed(player)

    • Logs step 4 when the client signals that the guide UI was closed

  • OnCoinCollected(player, coinAmount)

    • When called from the coin collection logic, logs the amount collected together with the area name

Checking Results in Creator Hub

Events logged in a published world and some errors that occurred while logging them can be checked in Creator Hub. Event times and daily aggregation are based on UTC.

Status
Description

Stored

The event was saved successfully

Invalid field format

The event was not saved because an argument or field format was invalid.

Check whether the values passed follow the parameter rules.

Rate limit exceeded

The event was not saved because the call limit was exceeded.

It is recommended to log events less frequently.

Delivery failed

The event was lost because the transmission failed.

If this keeps happening, contact the support channel.

Rejected by server

The server rejected some or all of the records.

If this keeps happening, contact the support channel.

Difference Between Actions in Published and Test Environments

Events are sent to Creator Hub and aggregated only in worlds published as public or private.

In a Play Test in Studio, only the arguments passed are checked, and events are not sent. Even if the code runs without errors in Studio, whether events are saved in Creator Hub must be checked in a published world.

Important Notes

  • The event logging functions can be called only from a server script. Calling them from a LocalScript causes an error.

  • Passing an invalid argument can cause an error. It is recommended to wrap the call in pcall() so that game logic is not affected.

  • Each server can log up to 120 + (20 × the number of players currently in the server) Custom Events and Onboarding Funnel Events combined in any 60-second window. Events beyond the limit are not saved and are not sent again.

    • For example, a server with 10 players can log up to 320 events in 60 seconds.

    • Do not log on every frame or on every repeated collision. Log once when a meaningful action is finished.

  • When the server shuts down, it keeps trying to send pending events for up to 10 seconds. Events not sent within that time may be lost.

  • Do not put personal information in event names or Custom Field values.

Usage Examples

  • If you log each tutorial step as an Onboarding Funnel, you can find in Creator Hub where the conversion rate drops sharply between steps. After adjusting the guidance or difficulty of that section, you can publish again and compare the change in conversion rate.

  • Actions such as entering a shop, buying an item, or clearing a boss can be logged as Custom Events and compared by map or difficulty with Custom Fields.

Last updated