roblox-analytics-liveops

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Analytics and live operations

数据分析与线上运营

Analytics events (server-side,
AnalyticsService
)

分析事件(服务器端,
AnalyticsService
)

Standard events feed the Creator Hub dashboards automatically (economy, funnels, progression, custom). The
Fire*
methods are deprecated; use the
Log*
family.
luau
--!strict
local AnalyticsService = game:GetService("AnalyticsService")

local Analytics = {}

-- Currency sources and sinks → Economy dashboard.
function Analytics.coinsEarned(player: Player, amount: number, balance: number, source: string)
	AnalyticsService:LogEconomyEvent(
		player,
		Enum.AnalyticsEconomyFlowType.Source,
		"Coins", -- currency type
		amount,
		balance, -- ending balance
		Enum.AnalyticsEconomyTransactionType.Gameplay.Name, -- or a custom string like "QuestReward"
		source -- item SKU / source id
	)
end

function Analytics.itemBought(player: Player, price: number, balance: number, itemSku: string)
	AnalyticsService:LogEconomyEvent(
		player,
		Enum.AnalyticsEconomyFlowType.Sink,
		"Coins",
		price,
		balance,
		Enum.AnalyticsEconomyTransactionType.Shop.Name,
		itemSku
	)
end

-- First-session tutorial funnel (steps must be sequential, 1-based).
function Analytics.onboarding(player: Player, step: number, stepName: string)
	AnalyticsService:LogOnboardingFunnelStepEvent(player, step, stepName)
end

-- Recurring funnels (e.g. shop purchase flow); share a session id per attempt.
function Analytics.shopFunnel(player: Player, sessionId: string, step: number, stepName: string)
	AnalyticsService:LogFunnelStepEvent(player, "ShopPurchase", sessionId, step, stepName)
end

-- Level progression.
function Analytics.levelStarted(player: Player, level: number)
	AnalyticsService:LogProgressionStartEvent(player, "MainPath", level, `Level{level}`)
end
function Analytics.levelCompleted(player: Player, level: number)
	AnalyticsService:LogProgressionCompleteEvent(player, "MainPath", level, `Level{level}`)
end

-- Anything else: numeric custom events, sliced by up to 3 custom fields.
function Analytics.bossKilled(player: Player, bossId: string, seconds: number)
	AnalyticsService:LogCustomEvent(player, "BossKillTime", seconds, {
		[Enum.AnalyticsCustomFieldKeys.CustomField01.Name] = bossId,
	})
end

return Analytics
Guidelines:
  • Log from the server (trustworthy, and required by these APIs). Keep event names and custom-field values low-cardinality (IDs of categories, not free text or user IDs).
  • Economy events need accurate
    endingBalance
    ; log every source and sink or the dashboard misleads.
  • Design funnels before building features (onboarding steps, shop flow, first purchase).
  • AnalyticsService:GetPlayerSegmentsAsync(player)
    returns segment info (payer status, account age in your game, ...) at runtime to tailor onboarding and offers —
    pcall
    it.
标准事件会自动将数据馈送至 Creator Hub 仪表板(经济、漏斗、进度、自定义)。
Fire*
方法已弃用;请使用
Log*
系列。
luau
--!strict
local AnalyticsService = game:GetService("AnalyticsService")

local Analytics = {}

-- Currency sources and sinks → Economy dashboard.
function Analytics.coinsEarned(player: Player, amount: number, balance: number, source: string)
	AnalyticsService:LogEconomyEvent(
		player,
		Enum.AnalyticsEconomyFlowType.Source,
		"Coins", -- currency type
		amount,
		balance, -- ending balance
		Enum.AnalyticsEconomyTransactionType.Gameplay.Name, -- or a custom string like "QuestReward"
		source -- item SKU / source id
	)
end

function Analytics.itemBought(player: Player, price: number, balance: number, itemSku: string)
	AnalyticsService:LogEconomyEvent(
		player,
		Enum.AnalyticsEconomyFlowType.Sink,
		"Coins",
		price,
		balance,
		Enum.AnalyticsEconomyTransactionType.Shop.Name,
		itemSku
	)
end

-- First-session tutorial funnel (steps must be sequential, 1-based).
function Analytics.onboarding(player: Player, step: number, stepName: string)
	AnalyticsService:LogOnboardingFunnelStepEvent(player, step, stepName)
end

-- Recurring funnels (e.g. shop purchase flow); share a session id per attempt.
function Analytics.shopFunnel(player: Player, sessionId: string, step: number, stepName: string)
	AnalyticsService:LogFunnelStepEvent(player, "ShopPurchase", sessionId, step, stepName)
end

-- Level progression.
function Analytics.levelStarted(player: Player, level: number)
	AnalyticsService:LogProgressionStartEvent(player, "MainPath", level, `Level{level}`)
end
function Analytics.levelCompleted(player: Player, level: number)
	AnalyticsService:LogProgressionCompleteEvent(player, "MainPath", level, `Level{level}`)
end

-- Anything else: numeric custom events, sliced by up to 3 custom fields.
function Analytics.bossKilled(player: Player, bossId: string, seconds: number)
	AnalyticsService:LogCustomEvent(player, "BossKillTime", seconds, {
		[Enum.AnalyticsCustomFieldKeys.CustomField01.Name] = bossId,
	})
end

return Analytics
指南:
  • 请从服务器端记录事件(数据可信,且这些 API 要求如此)。保持事件名称和自定义字段值的低基数(使用类别 ID,而不是自由文本或用户 ID)。
  • 经济事件必须提供准确的
    endingBalance
    ;记录所有流入和流出,否则仪表板会产生误导。
  • 在构建功能之前先设计漏斗(新手引导步骤、商店流程、首次购买)。
  • AnalyticsService:GetPlayerSegmentsAsync(player)
    可在运行时返回玩家分群信息(付费状态、游戏内账户年龄等),用于定制新手引导和优惠方案——请使用
    pcall
    调用。

Experience configs (live values without republishing)

体验配置(无需重新发布即可更新实时值)

Create configs in Creator Hub (or Open Cloud) — balance numbers, feature flags, event toggles — and read them on the server with
ConfigService
. Published changes arrive in running servers.
luau
--!strict
local ConfigService = game:GetService("ConfigService")

local ok, snapshot = pcall(function()
	return ConfigService:GetConfigAsync()
end)

local function get(key: string, default: any): any
	if not ok then
		return default
	end
	local value = snapshot:GetValue(key)
	return if value == nil then default else value
end

local bossHealth = get("bossHealth", 500)
print("boss health", bossHealth)

if ok then
	snapshot.UpdateAvailable:Connect(function()
		snapshot:Refresh() -- apply newly published values at a safe moment (e.g. between rounds)
		print("new boss health", get("bossHealth", 500))
	end)
end
  • Always code a default: configs may fail to load.
  • Experiments / targeted configs evaluate per player: use
    ConfigService:GetConfigForPlayerAsync(player)
    (
    GetConfigAsync
    ignores targeting). Experiments run 14–60 days, up to two variants plus control; pick a goal metric and respect the minimum detectable effect. Manage via Creator Hub or the Open Cloud experimentation API (
    roblox-open-cloud
    ).
  • Studio testing:
    ConfigService:SetTestingValue(key, value)
    /
    ClearTestingValue
    .
在 Creator Hub(或 Open Cloud)中创建配置——平衡数值、功能开关、活动开关等——并在服务器端使用
ConfigService
读取。已发布的更改会同步至正在运行的服务器。
luau
--!strict
local ConfigService = game:GetService("ConfigService")

local ok, snapshot = pcall(function()
	return ConfigService:GetConfigAsync()
end)

local function get(key: string, default: any): any
	if not ok then
		return default
	end
	local value = snapshot:GetValue(key)
	return if value == nil then default else value
end

local bossHealth = get("bossHealth", 500)
print("boss health", bossHealth)

if ok then
	snapshot.UpdateAvailable:Connect(function()
		snapshot:Refresh() -- apply newly published values at a safe moment (e.g. between rounds)
		print("new boss health", get("bossHealth", 500))
	end)
end
  • 始终设置默认值:配置可能加载失败。
  • 实验/定向配置会按玩家进行评估:请使用
    ConfigService:GetConfigForPlayerAsync(player)
    (
    GetConfigAsync
    会忽略定向规则)。实验持续 14–60 天,最多包含两个变体和一个对照组;请选择目标指标,并遵循最小可检测效应。可通过 Creator Hub 或 Open Cloud 实验 API(
    roblox-open-cloud
    )进行管理。
  • Studio 测试:
    ConfigService:SetTestingValue(key, value)
    /
    ClearTestingValue
    。

Badges

徽章

BadgeService:AwardBadgeAsync(userId, badgeId)
(server,
pcall
; skip if
UserHasBadgeAsync
or
CheckUserBadgesAsync
already says owned).
AwardBadge
/
UserHasBadge
are deprecated. Badges are great onboarding and progression milestones and show on players' profiles.
BadgeService:AwardBadgeAsync(userId, badgeId)
(服务器端,使用
pcall
;如果
UserHasBadgeAsync
或
CheckUserBadgesAsync
已表明玩家拥有该徽章,则跳过)。
AwardBadge
/
UserHasBadge
已弃用。徽章非常适合用作新手引导和进度里程碑,并会展示在玩家个人资料中。

Experience notifications (re-engagement)

体验通知(玩家再参与)

  1. Ask players to opt in at a meaningful moment:
    ExperienceNotificationService:CanPromptOptInAsync()
    then
    PromptOptIn()
    (client).
  2. Create notification strings in Creator Hub; send from your backend via Open Cloud
    POST /cloud/v2/users/{userId}/notifications
    (e.g. "your crops are ready", "event starts now"). Notifications are rate-limited and moderated; send ones players value.
  1. 在有意义的时机询问玩家是否选择加入:先调用
    ExperienceNotificationService:CanPromptOptInAsync()
    ,再由客户端调用
    PromptOptIn()
    。
  2. 在 Creator Hub 中创建通知文本;通过后端使用 Open Cloud
    POST /cloud/v2/users/{userId}/notifications
    发送(例如“你的作物已成熟”“活动现在开始”)。通知会受到频率限制和审核;只发送玩家真正重视的内容。

Live-ops patterns

线上运营模式

  • Timed events: schedule with UTC timestamps in a config (
    eventStart
    ,
    eventEnd
    ); compare with
    os.time()
    on the server; broadcast state via attributes; clients show countdowns from
    workspace:GetServerTimeNow()
    .
  • Season pass / rotating shops: rotation seed =
    math.floor(os.time() / 86400)
    for daily shops; store claimed rewards per season id in player data.
  • Daily rewards/streaks: store
    lastClaimDay
    (UTC day number) and streak count; grant on the server.
  • Ship content behind config flags, validate with a small rollout/experiment, then roll out to 100%.
  • Watch Creator Hub dashboards: retention (D1/D7/D30), session length, conversion, ARPPU, funnels, and performance (crash rate, FPS, memory) after every release.
  • 定时活动:在配置中使用 UTC 时间戳进行调度(
    eventStart
    、
    eventEnd
    );在服务器端与
    os.time()
    比较;通过 attributes 广播状态;客户端根据
    workspace:GetServerTimeNow()
    显示倒计时。
  • 赛季通行证/轮换商店:每日商店的轮换种子为
    math.floor(os.time() / 86400)
    ;按赛季 ID 将已领取奖励存储在玩家数据中。
  • 每日奖励/连续签到:存储
    lastClaimDay
    (UTC 天数)和连续签到次数;在服务器端发放奖励。
  • 通过配置开关控制内容上线,先以小范围推送/实验进行验证,然后逐步扩展至 100%。
  • 每次发布后都要关注 Creator Hub 仪表板:留存率(D1/D7/D30)、会话时长、转化率、ARPPU、漏斗,以及性能指标(崩溃率、FPS、内存)。

Related skills

相关 skill

roblox-monetization
(offers, pricing),
roblox-data-stores
(streaks, season data),
roblox-open-cloud
(configs/experiments/notifications APIs),
roblox-game-systems
.
roblox-monetization
(商品、定价)、
roblox-data-stores
(连续签到、赛季数据)、
roblox-open-cloud
(配置/实验/通知 API)、
roblox-game-systems
。