> 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/korean/manual/script-manual/advanced-gameplay-systems/analytics.md).

# 애널리틱스

## 개요

AnalyticsService를 사용하면 월드에서 플레이어가 한 행동을 이벤트로 기록하고, 배포한 뒤 **Creator Hub**에서 집계 결과를 확인할 수 있습니다.

튜토리얼에서 플레이어가 어느 단계까지 진행했는지, 어떤 행동을 얼마나 자주 했는지를 파악해 이탈 구간을 찾고 월드를 개선하는 데 활용할 수 있습니다.

## 구성 요소

<table><thead><tr><th width="234">구분</th><th>설명</th></tr></thead><tbody><tr><td>Custom Event</td><td><p>크리에이터가 이름과 값을 정해 기록하는 단발성 이벤트입니다.</p><p>코인 획득, 미션 클리어, 상점 진입처럼 특정 행동이 일어난 시점에 기록합니다.</p></td></tr><tr><td>Onboarding Funnel Event</td><td><p>플레이어의 튜토리얼(온보딩) 진행 단계를 기록하는 이벤트입니다.</p><p>단계별로 몇 명이 도달했는지 집계되어, 어느 단계에서 플레이어가 많이 이탈하는지 확인할 수 있습니다.</p></td></tr><tr><td>Custom Field</td><td>이벤트를 세부 조건별로 나누어 보기 위한 분류 값입니다. 이벤트 하나에 최대 <strong>3개</strong>까지 지정할 수 있습니다.</td></tr></tbody></table>

## 사용 방법

### 서비스 가져오기

AnalyticsService는 GetService()로 가져옵니다. 이벤트 기록 함수는 **서버 스크립트에서만** 호출할 수 있습니다.

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

<table><thead><tr><th width="330">기능</th><th>설명</th></tr></thead><tbody><tr><td>LogCustomEvent(player, eventName, value<em>(*optional)</em>, customFields<em>(*optional)</em>)</td><td>Custom Event 1건을 기록</td></tr><tr><td>LogOnboardingFunnelStepEvent(player, step, stepName<em>(*optional)</em>, customFields<em>(*optional)</em>)</td><td>온보딩 퍼널의 한 단계 도달을 기록</td></tr></tbody></table>

두 함수 모두 반환값이 없으며, 전송 결과를 기다리지 않고 바로 다음 코드로 진행합니다.

각 함수의 파라미터와 동작은 아래 메뉴얼에서도 확인할 수 있습니다.

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

### Custom Event 기록하기

<table><thead><tr><th width="234">파라미터</th><th>설명</th></tr></thead><tbody><tr><td>player</td><td>이벤트를 발생시킨 Player</td></tr><tr><td>eventName</td><td>이벤트 이름입니다. 빈 문자열은 사용할 수 없으며, 최대 <strong>50자</strong>까지 저장됩니다.</td></tr><tr><td>value</td><td>(선택) 이벤트에 함께 기록할 숫자입니다. 음수와 소수를 사용할 수 있으며, NaN과 무한대는 사용할 수 없습니다.</td></tr><tr><td>customFields</td><td>(선택) 이벤트를 분류할 Custom Field 테이블</td></tr></tbody></table>

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

local EventName = "MissionCompleted"

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

**value**를 생략한 이벤트와 **value**에 0을 전달한 이벤트는 서로 다른 값으로 저장됩니다. 생략하면 값이 없는 이벤트로, 0을 전달하면 값이 0인 이벤트로 기록됩니다.

발생 횟수만 확인하면 되는 이벤트는 **value**를 생략하고, 클리어 시간이나 획득량처럼 값 자체가 의미 있는 이벤트에만 **value**를 전달하는 것을 권장합니다.

### Onboarding Funnel 기록하기

<table><thead><tr><th width="234">파라미터</th><th>설명</th></tr></thead><tbody><tr><td>player</td><td>단계를 진행한 Player</td></tr><tr><td>step</td><td>단계 번호입니다. <strong>1 이상 100 이하</strong>의 숫자를 사용하며, 소수점 둘째 자리까지 지정할 수 있습니다.</td></tr><tr><td>stepName</td><td>(선택) Creator Hub에 표시할 단계 이름입니다. 최대 <strong>50자</strong>까지 저장됩니다.</td></tr><tr><td>customFields</td><td>(선택) 단계를 분류할 Custom Field 테이블</td></tr></tbody></table>

월드 입장을 1단계로 집계하려면 PlayerAdded 이벤트에서 1단계를 기록합니다.

```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)
```

#### 단계 번호 지정

단계 번호는 1부터 진행 순서대로 지정하는 것을 권장합니다.

이미 배포한 퍼널의 단계 사이에 새 단계를 추가할 때는 **소수**를 사용할 수 있습니다. 예를 들어 2단계와 3단계 사이에 **2.5**단계를 추가할 수 있습니다.

소수점 셋째 자리 이하가 포함된 값은 사용하지 않는 것을 권장합니다. 계산으로 구한 값은 소수점 둘째 자리까지 정리한 뒤 전달합니다.

```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)
```

#### 단계 집계 방식

* 같은 플레이어가 같은 단계를 여러 번 기록해도 단계 전환 집계에는 **처음 도달한 1회**만 반영됩니다.
* 중간 단계를 기록하지 않고 더 높은 단계를 기록하면, 그 앞의 단계도 완료한 것으로 집계됩니다.
* 기존 단계 사이에 새 단계를 추가하면, 이미 다음 단계에 도달한 플레이어도 새 단계를 완료한 것으로 집계됩니다. 단계를 추가하기 전과 후의 플레이어는 구분되지 않습니다.
* 같은 단계를 반복해서 기록한 호출도 호출량 제한에는 포함됩니다.

### Custom Field로 분류하기

Custom Field를 사용하면 같은 이벤트를 맵, 난이도, 획득 경로 등 조건별로 나누어 비교할 수 있습니다.

<table><thead><tr><th width="330">키</th><th>설명</th></tr></thead><tbody><tr><td>Enum.AnalyticsCustomFieldKeys.CustomField01</td><td>첫 번째 분류 값</td></tr><tr><td>Enum.AnalyticsCustomFieldKeys.CustomField02</td><td>두 번째 분류 값</td></tr><tr><td>Enum.AnalyticsCustomFieldKeys.CustomField03</td><td>세 번째 분류 값</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
```

* 키에는 Enum 항목의 **Name**을 사용합니다.
* 값에는 **문자열**만 사용할 수 있습니다. 숫자를 분류 값으로 쓰려면 tostring()으로 변환해 전달합니다.
* 정의되지 않은 키는 무시됩니다.
* 값은 최대 **50자**까지 저장됩니다.

### 클라이언트에서 발생한 행동 기록하기

UI 버튼 클릭처럼 클라이언트에서 발생한 행동은 RemoteEvent로 서버에 알린 뒤, 서버 스크립트에서 기록합니다.

이때 단계 번호나 이벤트 값은 **서버에서 정하는 것**을 권장합니다. 클라이언트가 보낸 값을 그대로 기록하면 의도하지 않은 값이 집계될 수 있습니다.

**LocalScript**

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

local function OnGuideClosed() -- 안내 UI를 닫았다고 서버에 알림
    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) -- 단계 번호는 서버에서 정함
    AnalyticsService:LogOnboardingFunnelStepEvent(player, GuideClosedStep, GuideClosedStepName)
end
C2S_GuideClosed.OnServerEvent:Connect(OnGuideClosed)
```

RemoteEvent와 관련된 자세한 내용은 아래 메뉴얼을 참고하세요.

{% content-ref url="/pages/rznBJB0DomrXzxffvYtu" %}
[서버-클라이언트 통신](https://docs.overdare.com/korean/manual/script-manual/events-and-communication/remoteevent.md)
{% endcontent-ref %}

### 문자열 길이

eventName, stepName, Custom Field 값은 각각 최대 **50자**까지 저장되며, 50자를 넘는 부분은 잘린 뒤 저장됩니다.

글자 수는 영문·숫자·한글 1자를 1로, 대부분의 이모지는 1자를 2 이상으로 계산합니다. 이모지가 50번째 글자 위치에 걸리면 이벤트가 저장되지 않을 수 있으므로, 이름에는 이모지를 사용하지 않는 것을 권장합니다.

## 전체 코드 예시

다음 코드는 플레이어가 **입장**하면 1단계를, **체크포인트**에 도착하면 2\~3단계를, **안내 UI를 닫으면** 4단계를 기록합니다. 튜토리얼 구역에서 코인을 획득하면 Custom Event를 함께 기록합니다.

Workspace에 **TutorialCheckpoints** 폴더를 만들고, 그 안에 단계 이름으로 Part를 배치한 뒤 각 Part에 **FunnelStep** Attribute(number)로 단계 번호를 지정합니다. ReplicatedStorage에는 **C2S\_GuideClosed** RemoteEvent를 추가합니다.

**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 = {} -- 플레이어별로 이미 기록한 단계

--------------------------------------------------------
local function LogFunnelStep(player, step, stepName) -- 퍼널 단계 기록. 인자가 잘못되어도 pcall로 호출한 쪽은 계속 실행
    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) -- 같은 방식으로 Custom Event 기록
    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) -- 1단계: 플레이어가 월드에 입장
    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) -- 2~3단계: 플레이어가 체크포인트에 도착. 플레이어마다 단계당 한 번만 기록
    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) -- 4단계: 클라이언트에서 안내 UI를 닫음. 단계 번호는 서버에서 정함
    LogFunnelStep(player, GuideClosedStep, GuideClosedStepName)
end
C2S_GuideClosed.OnServerEvent:Connect(OnGuideClosed)

--------------------------------------------------------
local function OnCoinCollected(player, coinAmount) -- Custom Event: 튜토리얼 구역에서 코인 획득
    LogCustom(player, CoinEventName, coinAmount, TutorialArea)
end
```

**LocalScript (StarterPlayerScripts)**

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

local function OnGuideClosed() -- 안내 UI의 닫기 버튼을 눌렀을 때 호출
    C2S_GuideClosed:FireServer()
end
```

* **LogFunnelStep(player, step, stepName) / LogCustom(player, eventName, value, area)**
  * 기록 함수를 pcall()로 감싸 호출
  * 잘못된 값이 전달되어도 이후 게임 로직은 계속 실행되며, 원인은 Output에 출력
* **OnPlayerAdded(player)**
  * 플레이어가 입장하면 1단계 기록
* **ConnectCheckpoint(checkpoint)**
  * 체크포인트 Part에 닿으면 Part의 FunnelStep Attribute와 이름으로 단계 기록
  * Touched는 한 번 닿을 때도 여러 번 발생하므로, 플레이어마다 이미 기록한 단계를 LoggedSteps에 저장해 한 번만 기록
  * 단계 번호를 Attribute로 관리하므로, 단계를 추가하거나 바꿀 때 스크립트를 수정하지 않아도 됨
* **OnGuideClosed(player)**
  * 클라이언트에서 안내 UI를 닫았다는 신호를 받으면 4단계 기록
* **OnCoinCollected(player, coinAmount)**
  * 코인을 획득한 처리에서 호출하면 획득량과 구역 이름을 함께 기록

## Creator Hub에서 결과 확인

배포한 월드에서 기록된 이벤트와, 기록 과정에서 발생한 일부 오류는 **Creator Hub**에서 확인할 수 있습니다. 이벤트 발생 시각과 일 단위 집계는 **UTC** 기준입니다.

<table><thead><tr><th width="234">상태</th><th>설명</th></tr></thead><tbody><tr><td>Stored</td><td>이벤트가 정상적으로 저장된 상태</td></tr><tr><td>Invalid field format</td><td><p>인자나 필드 형식이 올바르지 않아 이벤트가 저장되지 않은 상태입니다.</p><p>전달한 값이 파라미터 규칙에 맞는지 확인이 필요합니다.</p></td></tr><tr><td>Rate limit exceeded</td><td><p>호출량 제한을 초과해 이벤트가 저장되지 않은 상태입니다.</p><p>이벤트를 기록하는 빈도를 줄이는 것을 권장합니다.</p></td></tr><tr><td>Delivery failed</td><td><p>전송에 실패해 이벤트가 유실된 상태입니다.</p><p>계속 발생하면 고객 지원 채널로 문의가 필요합니다.</p></td></tr><tr><td>Rejected by server</td><td><p>서버가 일부 또는 전체 기록을 거부한 상태입니다.</p><p>계속 발생하면 고객 지원 채널로 문의가 필요합니다.</p></td></tr></tbody></table>

## 퍼블리시 및 테스트 환경의 동작 차이

이벤트는 **공개 또는 비공개로 배포한 월드**에서만 Creator Hub로 전송되어 집계됩니다.

스튜디오의 플레이 테스트에서는 전달한 인자가 올바른지만 확인하며, 이벤트는 전송되지 않습니다. 스튜디오에서 오류 없이 실행되었더라도 Creator Hub 저장 여부는 배포한 월드에서 확인해야 합니다.

{% hint style="warning" %}
호출량 제한은 배포한 월드에서만 적용됩니다. 스튜디오에서는 제한을 넘는 횟수로 호출해도 별도의 안내가 표시되지 않습니다.
{% endhint %}

## 주의 사항

* 이벤트 기록 함수는 **서버 스크립트에서만** 호출할 수 있습니다. LocalScript에서 호출하면 오류가 발생합니다.
* 잘못된 인자를 전달하면 오류가 발생할 수 있습니다. 게임 로직에 영향을 주지 않도록 pcall()로 감싸 호출하는 것을 권장합니다.
* Custom Event와 Onboarding Funnel Event는 합산하여 서버마다 최근 60초 동안 **120 + (20 × 현재 접속자 수)**&#xAC74;까지 기록됩니다. 초과한 이벤트는 저장되지 않으며 다시 전송되지 않습니다.
  * 예를 들어 접속자가 10명인 서버에서는 60초 동안 320건까지 기록됩니다.
  * 매 프레임이나 반복되는 충돌마다 기록하지 말고, 의미 있는 행동이 끝난 시점에 한 번 기록하세요.
* 서버가 종료될 때는 아직 전송되지 않은 이벤트를 최대 10초 동안 전송합니다. 그 안에 전송되지 않은 이벤트는 유실될 수 있습니다.
* 이벤트 이름과 Custom Field 값에 개인정보를 넣지 마세요.

## 활용 예시

* 튜토리얼의 각 단계를 Onboarding Funnel로 기록하면, Creator Hub에서 단계별 전환율이 급격히 떨어지는 구간을 찾을 수 있습니다. 해당 구간의 안내나 난이도를 조정한 뒤 다시 배포해 전환율 변화를 비교할 수 있습니다.
* 상점 진입, 아이템 구매, 보스 클리어 같은 행동은 Custom Event로 기록하고, Custom Field로 맵이나 난이도를 나누어 비교할 수 있습니다.
