roblox-analytics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Roblox Analytics Reference

Roblox Analytics参考文档

Overview

概述

Load this reference when the task involves:

Tracking player behavior, feature adoption, or engagement metrics
Implementing economy event logging (currency sources/sinks)
Building funnel tracking (onboarding, shop conversion, progression)
Custom event instrumentation for A/B testing or feature flags
Understanding rate limits and batching strategies

Roblox provides a first-party analytics system via

AnalyticsService

. No third-party SDK needed. Events feed directly into the Creator Hub analytics dashboard with 24-hour processing delay.

当任务涉及以下内容时，可查阅本参考文档：

追踪玩家行为、功能采用情况或参与度指标
实现经济事件日志记录（货币来源/消耗）
构建漏斗追踪（新手引导、商店转化、进度推进）
为A/B测试或功能标志实现自定义事件埋点
了解速率限制和批处理策略

Roblox通过

AnalyticsService

提供原生分析系统，无需第三方SDK。事件会直接传入Creator Hub分析仪表板，处理延迟为24小时。

Quick Reference

快速参考

Load Full Reference below only when you need specific API signatures or implementation patterns.

Key rules:

Use
```
AnalyticsService
```
(built-in). No third-party analytics SDK needed.
Three event types: Custom (counters/values), Economy (currency flow), Funnel (step progression)
Rate limit: 120 + (20 × CCU) calls per minute. Batch where possible.
Max 100 custom events, 10 economy resource types, 10 funnels, 3 custom fields per event.
Log events AFTER successful operations, not on attempt (avoids inflated metrics).
Custom fields (up to 3) let you slice data without burning event cardinality.
Economy events track sources (earned) and sinks (spent) separately.
Funnel events must fire steps in order. Skipped steps break the funnel.
Events appear on Creator Hub dashboard after ~24 hours. Use "View Events" for real-time validation.
Server-side logging preferred for accuracy. Client-side only for UI interaction tracking.

仅当需要特定API签名或实现模式时，才查看下方完整参考内容。

核心规则：

使用内置的
```
AnalyticsService
```
，无需第三方分析SDK。
三种事件类型：自定义事件（计数器/数值）、经济事件（货币流向）、漏斗事件（步骤进度）
速率限制：每分钟120 + (20 × CCU)次调用，尽可能使用批处理。
最多支持100个自定义事件、10种经济资源类型、10个漏斗、每个事件3个自定义字段。
在操作成功后记录事件，而非尝试操作时（避免指标虚高）。
自定义字段（最多3个）可让你在不增加事件基数的情况下拆分数据。
经济事件需分别追踪来源（获取）和消耗（支出）。
漏斗事件必须按顺序触发步骤，跳过步骤会破坏漏斗分析。
事件会在约24小时后出现在Creator Hub仪表板，可使用“查看事件”功能进行实时验证。
优先使用服务器端日志记录以保证准确性，客户端仅用于UI交互追踪。

Full Reference

完整参考

1. AnalyticsService API

All methods are called on the server via

game:GetService("AnalyticsService")

所有方法均通过服务器端的

game:GetService("AnalyticsService")

调用。

Custom Events

自定义事件

Track any game-specific metric. Two forms: counter (no value) and valued.

luau

local AnalyticsService = game:GetService("AnalyticsService")

-- Counter: tracks occurrence count + unique users automatically
AnalyticsService:LogCustomEvent(player, "MissionStarted")

-- With value: enables sum/mean/min/max aggregations
AnalyticsService:LogCustomEvent(player, "MissionCompletedDuration", 120)

-- With custom fields (up to 3): enables filtering/breakdown on dashboard
AnalyticsService:LogCustomEvent(player, "EnemyDefeated", 1, {
    customFields = {
        [Enum.AnalyticsCustomFieldKeys.CustomField01] = { value = "Zombie" },
        [Enum.AnalyticsCustomFieldKeys.CustomField02] = { value = "Sword" },
        [Enum.AnalyticsCustomFieldKeys.CustomField03] = { value = "Wave5" },
    }
})

追踪任何游戏特定指标，分为两种形式：计数器（无数值）和带数值的事件。

luau

local AnalyticsService = game:GetService("AnalyticsService")

-- 计数器：自动追踪事件发生次数和唯一用户数
AnalyticsService:LogCustomEvent(player, "MissionStarted")

-- 带数值：支持求和/平均值/最小值/最大值聚合
AnalyticsService:LogCustomEvent(player, "MissionCompletedDuration", 120)

-- 带自定义字段（最多3个）：可在仪表板上进行筛选/细分
AnalyticsService:LogCustomEvent(player, "EnemyDefeated", 1, {
    customFields = {
        [Enum.AnalyticsCustomFieldKeys.CustomField01] = { value = "Zombie" },
        [Enum.AnalyticsCustomFieldKeys.CustomField02] = { value = "Sword" },
        [Enum.AnalyticsCustomFieldKeys.CustomField03] = { value = "Wave5" },
    }
})

Economy Events

经济事件

Track virtual currency flow. Enables revenue analysis, inflation detection, economy health.

luau

-- Player EARNED currency (source)
AnalyticsService:LogEconomyEvent(
    player,
    Enum.AnalyticsEconomyFlowType.Source, -- Source = earned/gained
    "Coins",                               -- Currency name (max 10 types)
    50,                                    -- Amount
    player.leaderstats.Coins.Value + 50,   -- Balance AFTER transaction
    Enum.AnalyticsEconomyTransactionType.Gameplay.Name, -- Transaction type
    "QuestReward_Daily",                   -- Item SKU (what triggered it)
    {
        customFields = {
            [Enum.AnalyticsCustomFieldKeys.CustomField01] = { value = "Quest_001" },
        }
    }
)

-- Player SPENT currency (sink)
AnalyticsService:LogEconomyEvent(
    player,
    Enum.AnalyticsEconomyFlowType.Sink, -- Sink = spent/consumed
    "Coins",
    200,
    player.leaderstats.Coins.Value - 200,
    Enum.AnalyticsEconomyTransactionType.Shop.Name,
    "SpeedBoost_30min"
)

Transaction types:

Gameplay

ContextualPurchase

InAppPurchase

Shop

TimedReward

Trade

追踪虚拟货币流向，支持收入分析、通胀检测和经济健康评估。

luau

-- 玩家获取货币（来源）
AnalyticsService:LogEconomyEvent(
    player,
    Enum.AnalyticsEconomyFlowType.Source, -- Source = 获取/获得
    "Coins",                               -- 货币名称（最多10种类型）
    50,                                    -- 数量
    player.leaderstats.Coins.Value + 50,   -- 交易后的余额
    Enum.AnalyticsEconomyTransactionType.Gameplay.Name, -- 交易类型
    "QuestReward_Daily",                   -- 触发交易的物品SKU
    {
        customFields = {
            [Enum.AnalyticsCustomFieldKeys.CustomField01] = { value = "Quest_001" },
        }
    }
)

-- 玩家消耗货币（支出）
AnalyticsService:LogEconomyEvent(
    player,
    Enum.AnalyticsEconomyFlowType.Sink, -- Sink = 消耗/支出
    "Coins",
    200,
    player.leaderstats.Coins.Value - 200,
    Enum.AnalyticsEconomyTransactionType.Shop.Name,
    "SpeedBoost_30min"
)

交易类型：

Gameplay

、

ContextualPurchase

、

InAppPurchase

、

Shop

、

TimedReward

、

Trade

。

Funnel Events

漏斗事件

Track step-by-step progression through a flow. Max 10 funnels, 100 steps each.

luau

-- Onboarding funnel: track where players drop off
AnalyticsService:LogFunnelStepEvent(player, "Onboarding", "1", "WelcomeScreen")
-- ... player progresses ...
AnalyticsService:LogFunnelStepEvent(player, "Onboarding", "2", "PickCharacter")
-- ... player progresses ...
AnalyticsService:LogFunnelStepEvent(player, "Onboarding", "3", "FirstBattle")
-- ... player progresses ...
AnalyticsService:LogFunnelStepEvent(player, "Onboarding", "4", "CompleteTutorial")

-- Shop conversion funnel
AnalyticsService:LogFunnelStepEvent(player, "ShopPurchase", "1", "OpenedShop")
AnalyticsService:LogFunnelStepEvent(player, "ShopPurchase", "2", "ViewedItem")
AnalyticsService:LogFunnelStepEvent(player, "ShopPurchase", "3", "ClickedBuy")
AnalyticsService:LogFunnelStepEvent(player, "ShopPurchase", "4", "ConfirmedPurchase")

Steps MUST fire in order for the same player in the same session. Skipping step 2 and firing step 3 breaks the funnel visualization.

追踪流程中的分步进度，最多支持10个漏斗，每个漏斗最多100个步骤。

luau

-- 新手引导漏斗：追踪玩家在哪个环节流失
AnalyticsService:LogFunnelStepEvent(player, "Onboarding", "1", "WelcomeScreen")
-- ... 玩家推进进度 ...
AnalyticsService:LogFunnelStepEvent(player, "Onboarding", "2", "PickCharacter")
-- ... 玩家推进进度 ...
AnalyticsService:LogFunnelStepEvent(player, "Onboarding", "3", "FirstBattle")
-- ... 玩家推进进度 ...
AnalyticsService:LogFunnelStepEvent(player, "Onboarding", "4", "CompleteTutorial")

-- 商店转化漏斗
AnalyticsService:LogFunnelStepEvent(player, "ShopPurchase", "1", "OpenedShop")
AnalyticsService:LogFunnelStepEvent(player, "ShopPurchase", "2", "ViewedItem")
AnalyticsService:LogFunnelStepEvent(player, "ShopPurchase", "3", "ClickedBuy")
AnalyticsService:LogFunnelStepEvent(player, "ShopPurchase", "4", "ConfirmedPurchase")

同一玩家在同一会话中必须按顺序触发步骤，跳过步骤2直接触发步骤3会破坏漏斗可视化效果。

2. Rate Limits and Batching

2. 速率限制与批处理

Constraint	Limit
Total AnalyticsService calls/minute	120 + (20 × CCU)
Custom event names	100
Economy resource types	10
Funnels	10
Steps per funnel	100
Custom fields per event	3
Unique values per custom field	8,000 (then grouped as "Other")

约束条件	限制值
每分钟AnalyticsService调用总数	120 + (20 × CCU)
自定义事件名称数量	100
经济资源类型数量	10
漏斗数量	10
每个漏斗的步骤数量	100
每个事件的自定义字段数量	3
每个自定义字段的唯一值数量	8000（超过后会被归为“其他”）

Batching Strategy

批处理策略

For high-frequency events (kills, item pickups), batch on the server:

luau

-- ServerScriptService/Analytics/EventBatcher.luau

local AnalyticsService = game:GetService("AnalyticsService")

local EventBatcher = {}
local batches: { [Player]: { [string]: number } } = {}

-- Accumulate events, flush periodically
function EventBatcher:increment(player: Player, eventName: string, amount: number?)
    if not batches[player] then
        batches[player] = {}
    end
    local current = batches[player][eventName] or 0
    batches[player][eventName] = current + (amount or 1)
end

function EventBatcher:flush()
    for player, events in batches do
        if not player:IsDescendantOf(game.Players) then
            batches[player] = nil
            continue
        end
        for eventName, value in events do
            AnalyticsService:LogCustomEvent(player, eventName, value)
        end
    end
    batches = {}
end

-- Flush every 30 seconds
task.spawn(function()
    while true do
        task.wait(30)
        EventBatcher:flush()
    end
end)

-- Flush on player leaving (capture final counts)
game.Players.PlayerRemoving:Connect(function(player)
    if batches[player] then
        for eventName, value in batches[player] do
            AnalyticsService:LogCustomEvent(player, eventName, value)
        end
        batches[player] = nil
    end
end)

return EventBatcher

对于高频事件（击杀、物品拾取），在服务器端进行批处理：

luau

-- ServerScriptService/Analytics/EventBatcher.luau

local AnalyticsService = game:GetService("AnalyticsService")

local EventBatcher = {}
local batches: { [Player]: { [string]: number } } = {}

-- 累积事件，定期刷新
function EventBatcher:increment(player: Player, eventName: string, amount: number?)
    if not batches[player] then
        batches[player] = {}
    end
    local current = batches[player][eventName] or 0
    batches[player][eventName] = current + (amount or 1)
end

function EventBatcher:flush()
    for player, events in batches do
        if not player:IsDescendantOf(game.Players) then
            batches[player] = nil
            continue
        end
        for eventName, value in events do
            AnalyticsService:LogCustomEvent(player, eventName, value)
        end
    end
    batches = {}
end

-- 每30秒刷新一次
task.spawn(function()
    while true do
        task.wait(30)
        EventBatcher:flush()
    end
end)

-- 玩家离开时刷新（捕获最终计数）
game.Players.PlayerRemoving:Connect(function(player)
    if batches[player] then
        for eventName, value in batches[player] do
            AnalyticsService:LogCustomEvent(player, eventName, value)
        end
        batches[player] = nil
    end
end)

return EventBatcher

3. Event Taxonomy (Recommended)

3. 事件分类体系（推荐）

Use consistent naming. Custom fields for breakdown, not separate event names.

使用统一的命名规范，用自定义字段进行细分，而非创建单独的事件名称。

DO: Use custom fields for variants

正确做法：使用自定义字段区分变体

luau

-- ONE event, broken down by weapon type via custom field
AnalyticsService:LogCustomEvent(player, "EnemyKill", 1, {
    customFields = {
        [Enum.AnalyticsCustomFieldKeys.CustomField01] = { value = weaponType },
        [Enum.AnalyticsCustomFieldKeys.CustomField02] = { value = enemyType },
    }
})

luau

-- 单个事件，通过自定义字段区分武器类型
AnalyticsService:LogCustomEvent(player, "EnemyKill", 1, {
    customFields = {
        [Enum.AnalyticsCustomFieldKeys.CustomField01] = { value = weaponType },
        [Enum.AnalyticsCustomFieldKeys.CustomField02] = { value = enemyType },
    }
})

DON'T: Create separate events per variant

错误做法：为每个变体创建单独事件

luau

-- BAD: burns through your 100 event limit fast
AnalyticsService:LogCustomEvent(player, "EnemyKill_Sword")
AnalyticsService:LogCustomEvent(player, "EnemyKill_Bow")
AnalyticsService:LogCustomEvent(player, "EnemyKill_Magic")

luau

-- 错误：会快速耗尽100个事件的限制
AnalyticsService:LogCustomEvent(player, "EnemyKill_Sword")
AnalyticsService:LogCustomEvent(player, "EnemyKill_Bow")
AnalyticsService:LogCustomEvent(player, "EnemyKill_Magic")

Common Event Taxonomy

常见事件分类体系

Retention signals:

```
SessionStart
```
- counter, fire on PlayerAdded
```
SessionDuration
```
- value (seconds), fire on PlayerRemoving
```
DayNReturn
```
- counter with custom field for day number (Day1, Day7, Day30)

Engagement:

```
FeatureUsed
```
- custom field 1 = feature name
```
QuestCompleted
```
- custom field 1 = quest ID
```
LevelReached
```
- value = level number

Monetization funnel:

Funnel "Purchase": OpenedShop → ViewedItem → ClickedBuy → Confirmed → Granted
Economy source: IAP, QuestReward, DailyLogin, Trade
Economy sink: ShopPurchase, Upgrade, Trade

Progression:

Funnel "Onboarding": each tutorial step
Funnel "BossAttempt": Started → Phase1 → Phase2 → Defeated

留存信号：

```
SessionStart
```
- 计数器，在PlayerAdded时触发
```
SessionDuration
```
- 数值（秒），在PlayerRemoving时触发
```
DayNReturn
```
- 计数器，自定义字段为天数（Day1、Day7、Day30）

参与度：

```
FeatureUsed
```
- 自定义字段1 = 功能名称
```
QuestCompleted
```
- 自定义字段1 = 任务ID
```
LevelReached
```
- 数值 = 等级数

变现漏斗：

漏斗“Purchase”：OpenedShop → ViewedItem → ClickedBuy → Confirmed → Granted
经济来源：IAP、QuestReward、DailyLogin、Trade
经济消耗：ShopPurchase、Upgrade、Trade

进度推进：

漏斗“Onboarding”：每个教程步骤
漏斗“BossAttempt”：Started → Phase1 → Phase2 → Defeated

4. Validation and Debugging

4. 验证与调试

Real-time event validation

实时事件验证

Navigate to Creator Hub → Analytics → Custom/Economy/Funnel
Click "View Events" at the top
Events appear in near real-time (seconds, not the 24-hour dashboard delay)
Refresh to see new events

导航至Creator Hub → Analytics → Custom/Economy/Funnel
点击顶部的“View Events”
事件会近乎实时显示（几秒内，而非24小时的仪表板延迟）
刷新页面查看新事件

Common mistakes

常见错误

Logging on attempt instead of success (inflates metrics)
Logging from client (exploiters can spam fake events)
Exceeding rate limits silently (events get dropped, no error)
Using too many unique event names (100 limit, then new ones are ignored)
Firing funnel steps out of order (breaks the visualization)
Not logging economy balance (makes inflation analysis impossible)

在尝试操作时记录事件而非成功后（导致指标虚高）
从客户端记录事件（Exploiter可以伪造事件刷量）
静默超出速率限制（事件会被丢弃，无错误提示）
使用过多唯一事件名称（超过100个限制后，新事件会被忽略）
按错误顺序触发漏斗步骤（破坏可视化效果）
未记录经济余额（无法进行通胀分析）

5. Best Practices

5. 最佳实践

Log from server, not client. Client events can be spoofed.
Log AFTER the action succeeds, not when attempted.
Use the event batcher for high-frequency events (kills, pickups, damage dealt).
Keep event names stable across updates. Renaming breaks historical comparison.
Use custom fields for dimensions you want to filter by (weapon, map, class).
Track both sources and sinks for every currency to detect inflation.
Implement all funnels on day 1. Adding them later means no historical baseline.
Test with "View Events" before relying on the 24-hour dashboard.

从服务器端记录事件，而非客户端，客户端事件可能被篡改。
在操作成功后记录事件，而非尝试操作时。
对高频事件（击杀、拾取、伤害输出）使用事件批处理器。
在版本更新中保持事件名称稳定，重命名会破坏历史数据对比。
使用自定义字段存储你想要筛选的维度（武器、地图、职业）。
追踪每种货币的来源和消耗，以检测通胀。
在第一天就实现所有漏斗，后期添加会缺少历史基准数据。
在依赖24小时仪表板之前，先用“View Events”进行测试。