> For the complete documentation index, see [llms.txt](https://docs.overdare.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.overdare.com/manual/script-manual/advanced-gameplay-systems/analytics.md).

# 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

<table><thead><tr><th width="234">Type</th><th>Description</th></tr></thead><tbody><tr><td>Custom Event</td><td><p>A one-off event whose name and value are defined by the creator.</p><p>Log it at the moment a specific action happens, such as collecting a coin, clearing a mission, or entering a shop.</p></td></tr><tr><td>Onboarding Funnel Event</td><td><p>An event that logs players' tutorial (onboarding) progress.</p><p>The number of players who reach each step is aggregated, so you can see at which step many players drop off.</p></td></tr><tr><td>Custom Field</td><td>A breakdown value used to view events by detailed conditions. Up to <strong>3</strong> can be specified per event.</td></tr></tbody></table>

## How to Use

### Getting the Service

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

```lua
local AnalyticsService = game:GetService("AnalyticsService")
```

<table><thead><tr><th width="330">Function</th><th>Description</th></tr></thead><tbody><tr><td>LogCustomEvent(player, eventName, value<em>(*optional)</em>, customFields<em>(*optional)</em>)</td><td>Logs one Custom Event</td></tr><tr><td>LogOnboardingFunnelStepEvent(player, step, stepName<em>(*optional)</em>, customFields<em>(*optional)</em>)</td><td>Logs that a player reached a step of the onboarding funnel</td></tr></tbody></table>

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.

{% content-ref url="/pages/zx7BaVcFFBe1eWa9a5wC" %}
[AnalyticsService](https://docs.overdare.com/development/api-reference/classes/analyticsservice.md)
{% endcontent-ref %}

### Logging a Custom Event

<table><thead><tr><th width="234">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>player</td><td>The Player who triggered the event</td></tr><tr><td>eventName</td><td>The name of the event. An empty string cannot be used, and up to <strong>50 characters</strong> are saved.</td></tr><tr><td>value</td><td>(Optional) A number logged with the event. Negative numbers and decimals can be used, but NaN and infinity cannot.</td></tr><tr><td>customFields</td><td>(Optional) A Custom Field table used to break down the event</td></tr></tbody></table>

```lua
local AnalyticsService = game:GetService("AnalyticsService")

local EventName = "MissionCompleted"

local function OnMissionCompleted(player, clearTime)
    AnalyticsService:LogCustomEvent(player, EventName, clearTime)
end
```

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

<table><thead><tr><th width="234">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>player</td><td>The Player who progressed through the step</td></tr><tr><td>step</td><td>The step number. Use a number <strong>from 1 to 100</strong>, with up to two decimal places.</td></tr><tr><td>stepName</td><td>(Optional) The step name shown in Creator Hub. Up to <strong>50 characters</strong> are saved.</td></tr><tr><td>customFields</td><td>(Optional) A Custom Field table used to break down the step</td></tr></tbody></table>

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

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

local JoinStep = 1
local JoinStepName = "Join"

local function OnPlayerAdded(player)
    AnalyticsService:LogOnboardingFunnelStepEvent(player, JoinStep, JoinStepName)
end
Players.PlayerAdded:Connect(OnPlayerAdded)
```

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

```lua
local function RoundStep(rawStep: number)
    return math.floor(rawStep * 100 + 0.5) / 100
end

local RawStep = 2.456
local Step = RoundStep(RawStep)
print("Step : ", Step)
```

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

<table><thead><tr><th width="330">Key</th><th>Description</th></tr></thead><tbody><tr><td>Enum.AnalyticsCustomFieldKeys.CustomField01</td><td>The first breakdown value</td></tr><tr><td>Enum.AnalyticsCustomFieldKeys.CustomField02</td><td>The second breakdown value</td></tr><tr><td>Enum.AnalyticsCustomFieldKeys.CustomField03</td><td>The third breakdown value</td></tr></tbody></table>

```lua
local AnalyticsService = game:GetService("AnalyticsService")

local FieldArea = Enum.AnalyticsCustomFieldKeys.CustomField01.Name
local FieldResult = Enum.AnalyticsCustomFieldKeys.CustomField02.Name
local EventName = "MissionCompleted"

local function OnMissionCompleted(player, clearTime)
    local customFields = {
        [FieldArea] = "Tutorial",
        [FieldResult] = "FirstClear",
    }
    AnalyticsService:LogCustomEvent(player, EventName, clearTime, customFields)
end
```

* 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**

```lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local C2S_GuideClosed = ReplicatedStorage:WaitForChild("C2S_GuideClosed")

local function OnGuideClosed() -- Tell the server that the guide UI was closed
    C2S_GuideClosed:FireServer()
end
```

**Script**

```lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local AnalyticsService = game:GetService("AnalyticsService")

local C2S_GuideClosed = ReplicatedStorage:WaitForChild("C2S_GuideClosed")

local GuideClosedStep = 4
local GuideClosedStepName = "CloseGuide"

local function OnGuideClosed(player) -- The step number is decided on the server
    AnalyticsService:LogOnboardingFunnelStepEvent(player, GuideClosedStep, GuideClosedStepName)
end
C2S_GuideClosed.OnServerEvent:Connect(OnGuideClosed)
```

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

{% content-ref url="/pages/mfqBcNA4eO76WSB23UO8" %}
[Server-Client Communication](https://docs.overdare.com/manual/script-manual/events-and-communication/remoteevent.md)
{% endcontent-ref %}

### 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)**

```lua
local Players = game:GetService("Players")
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local AnalyticsService = game:GetService("AnalyticsService")

local TutorialCheckpoints = workspace:WaitForChild("TutorialCheckpoints")
local C2S_GuideClosed = ReplicatedStorage:WaitForChild("C2S_GuideClosed")

local FieldOnboarding = Enum.AnalyticsCustomFieldKeys.CustomField01.Name
local FieldArea = Enum.AnalyticsCustomFieldKeys.CustomField02.Name

local JoinStep = 1
local JoinStepName = "Join"
local GuideClosedStep = 4
local GuideClosedStepName = "CloseGuide"
local CoinEventName = "CoinCollected"
local TutorialArea = "Tutorial"

local LoggedSteps = {} -- Steps already logged for each player

--------------------------------------------------------
local function LogFunnelStep(player, step, stepName) -- Log a funnel step. pcall keeps the caller running even if an argument is invalid.
    local customFields = {
        [FieldOnboarding] = "DefaultOnboarding",
    }
    local function SendEvent()
        AnalyticsService:LogOnboardingFunnelStepEvent(player, step, stepName, customFields)
    end

    local success, errorMessage = pcall(SendEvent)
    if not success then
        print("errorMessage : ", errorMessage)
    end
end

local function LogCustom(player, eventName, value, area) -- Log a custom event in the same way
    local customFields = {
        [FieldArea] = area,
    }
    local function SendEvent()
        AnalyticsService:LogCustomEvent(player, eventName, value, customFields)
    end

    local success, errorMessage = pcall(SendEvent)
    if not success then
        print("errorMessage : ", errorMessage)
    end
end

--------------------------------------------------------
local function OnPlayerAdded(player) -- Step 1: the player joined the world
    LoggedSteps[player] = {}
    LogFunnelStep(player, JoinStep, JoinStepName)
end
Players.PlayerAdded:Connect(OnPlayerAdded)

local function OnPlayerRemoving(player)
    LoggedSteps[player] = nil
end
Players.PlayerRemoving:Connect(OnPlayerRemoving)

--------------------------------------------------------
local function ConnectCheckpoint(checkpoint) -- Steps 2~3: the player reached a checkpoint. Each step is logged once per player.
    local step = checkpoint:GetAttribute("FunnelStep")
    local stepName = checkpoint.Name

    local function OnTouched(hit)
        local player = Players:GetPlayerFromCharacter(hit.Parent)
        if player and LoggedSteps[player] and not LoggedSteps[player][step] then
            LoggedSteps[player][step] = true
            LogFunnelStep(player, step, stepName)
        end
    end
    checkpoint.Touched:Connect(OnTouched)
end

for _, checkpoint in ipairs(TutorialCheckpoints:GetChildren()) do
    ConnectCheckpoint(checkpoint)
end

--------------------------------------------------------
local function OnGuideClosed(player) -- Step 4: the client closed the guide UI. The step number is decided on the server.
    LogFunnelStep(player, GuideClosedStep, GuideClosedStepName)
end
C2S_GuideClosed.OnServerEvent:Connect(OnGuideClosed)

--------------------------------------------------------
local function OnCoinCollected(player, coinAmount) -- Custom event: coins collected in the tutorial area
    LogCustom(player, CoinEventName, coinAmount, TutorialArea)
end
```

**LocalScript (StarterPlayerScripts)**

```lua
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local C2S_GuideClosed = ReplicatedStorage:WaitForChild("C2S_GuideClosed")

local function OnGuideClosed() -- Call this when the close button of the guide UI is pressed
    C2S_GuideClosed:FireServer()
end
```

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

<table><thead><tr><th width="234">Status</th><th>Description</th></tr></thead><tbody><tr><td>Stored</td><td>The event was saved successfully</td></tr><tr><td>Invalid field format</td><td><p>The event was not saved because an argument or field format was invalid.</p><p>Check whether the values passed follow the parameter rules.</p></td></tr><tr><td>Rate limit exceeded</td><td><p>The event was not saved because the call limit was exceeded.</p><p>It is recommended to log events less frequently.</p></td></tr><tr><td>Delivery failed</td><td><p>The event was lost because the transmission failed.</p><p>If this keeps happening, contact the support channel.</p></td></tr><tr><td>Rejected by server</td><td><p>The server rejected some or all of the records.</p><p>If this keeps happening, contact the support channel.</p></td></tr></tbody></table>

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

{% hint style="warning" %}
The call limit applies only in published worlds. In Studio, no notice is displayed even if the number of calls exceeds the limit.
{% endhint %}

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