主题
AnalyticsService
概览
| 字段 | 值 |
|---|---|
| Kind | Service · 服务 Service |
| Realm | server |
继承关系
- Unit（4 属性 / 25 函数 / 6 事件）
- [AnalyticsService]（10 函数）
> Service 继承 Unit 仅表示运行时类型关系；作者可用 API 以当前 Service 页面显式列出的成员为准，不自动包含 Unit 的创建、层级或销毁能力。
数据分析与事件追踪服务，负责把玩家在游戏内产生的自定义事件、经济流水、新手引导漏斗、进阶流程与属性变更等埋点上报给分析后台，并提供玩家分群查询能力。它面向服务端使用，所有上报接口都要求传入目标 Player 实例，便于把数据归属到具体玩家。
适用场景
典型场景是在玩家进入地图、完成关卡、消耗或获得货币、走到某个引导节点以及达成进阶目标时上报埋点，例如用进阶系列接口记录关卡开始与通关，用经济流水接口记录金币变动，再借助 GetPlayerSegmentsAsync 取得玩家分群用于差异化投放。
使用要点
先通过 game:GetService("AnalyticsService") 取得服务实例，然后按事件类型选择接口：通用事件用 LogCustomEvent，货币流动用 LogEconomyEvent，新手引导用 LogOnboardingFunnelStepEvent，自定义漏斗用 LogFunnelStepEvent，进阶流程用 LogProgressionStartEvent、LogProgressionCompleteEvent、LogProgressionFailEvent 或统一的 LogProgressionEvent，属性变化用 LogTrackDataChange。需要了解玩家分层时调用 GetPlayerSegmentsAsync 取回分群表，调用时始终把服务端的 Player 作为第一个参数传入。
注意事项
AnalyticsService 的非 progression 自定义数据 customData 只允许 CustomField01、CustomField02、CustomField03 三个 key；progression 系列事件的 customData 可使用业务自定义 key。所有埋点调用都应在服务端传入当前 Space 内的 Player。
代码示例
上报业务提供的关卡开始事件
lua
-- @runtime server
local analyticsService = game:GetService("AnalyticsService")
local function reportProgressStart(player, progressionPathName, level, levelName)
if player == nil or progressionPathName == nil or levelName == nil then return end
analyticsService:LogProgressionStartEvent(player, progressionPathName, level, levelName, nil)
end
-- 完成或失败时应在对应生命周期节点分别调用 Complete 或 Fail 接口关联类型
函数 (10)
LogCustomEvent
签名：LogCustomEvent(player: Player, eventName: String, value: Float, customData: Table) -> void
记录指定玩家的自定义事件，事件由事件名、事件值与附加数据表共同描述。
| 参数 | 类型 | 说明 |
|---|---|---|
player | Player | 玩家对象（事件归属，必须在当前 Space 内） |
eventName | String | 事件名称（非空，≤50 字符，仅允许 [a-zA-Z0-9_]） |
value | Float | 事件值，用于 sum/avg 聚合（number，缺省 1） |
customData | Table | 自定义数据（key 仅限 CustomField01/02/03；value 支持 str/int/float/bool，str≤256 且不含逗号、引号、换行符） |
返回值 void
示例代码
记录带规范自定义字段的事件
lua
-- @runtime server
local analyticsService = game:GetService("AnalyticsService")
local players = game:GetService("Players")
local allPlayers = players:GetPlayers()
local player = allPlayers[1]
if player ~= nil then
analyticsService:LogCustomEvent(player, "LevelUp", 10, {
CustomField01 = "hard",
CustomField02 = "chapter_1",
})
endLogEconomyEvent
签名：LogEconomyEvent(player: Player, flowType: String, currencyType: String, amount: Float, endingBalance: Float, transactionType: String, itemSku: String, customData: Table) -> void
记录指定玩家的经济事件，完整描述一次经济流动，包括流向、货币类型、数量、期末余额、交易类型、物品 SKU 与附加数据。
| 参数 | 类型 | 说明 |
|---|---|---|
player | Player | 玩家对象（事件归属，必须在当前 Space 内） |
flowType | String | 流向类型（仅 Source / Sink） |
currencyType | String | 货币类型（非空，≤50 字符，仅允许 [a-zA-Z0-9_]） |
amount | Float | 变化数量（必须 >0） |
endingBalance | Float | 结束余额（必须 >=0） |
transactionType | String | 交易类型（非空，≤50 字符，仅 [a-zA-Z0-9_]；推荐使用 IAP/Shop/Gameplay/ContextualPurchase/TimedReward/Onboarding） |
itemSku | String | 物品SKU（可选，≤50 字符） |
customData | Table | 自定义数据（key 仅限 CustomField01/02/03；value 支持 str/int/float/bool，str≤256 且不含逗号、引号、换行符） |
返回值 void
示例代码
记录内购货币收入
lua
-- @runtime server
local analyticsService = game:GetService('AnalyticsService')
local Players = game:GetService('Players')
local player = Players:GetPlayers()[1]
if player == nil then return end
analyticsService:LogEconomyEvent(
player,
'Source',
'Coins',
1000,
5000,
'IAP',
'1000CoinBundle',
{ CustomField01 = 'shop' }
)LogOnboardingFunnelStepEvent
签名：LogOnboardingFunnelStepEvent(player: Player, step: Int, stepName: String, customData: Table) -> void
记录指定玩家在新手引导漏斗中的步骤事件，包含步骤序号、步骤名与附加数据。
| 参数 | 类型 | 说明 |
|---|---|---|
player | Player | 玩家对象（事件归属，必须在当前 Space 内） |
step | Int | 步骤编号（整数 1-100） |
stepName | String | 步骤名称（可选，≤50 字符） |
customData | Table | 自定义数据（key 仅限 CustomField01/02/03；value 支持 str/int/float/bool，str≤256 且不含逗号、引号、换行符） |
返回值 void
示例代码
上报业务提供的新手引导步骤
lua
-- @runtime server
local analyticsService = game:GetService("AnalyticsService")
local function reportOnboardingStep(player, step, stepName)
if player == nil or stepName == nil then return end
analyticsService:LogOnboardingFunnelStepEvent(player, step, stepName, {})
end
-- 由业务流程传入真实步骤编号和名称LogFunnelStepEvent
签名：LogFunnelStepEvent(player: Player, funnelName: String, funnelSessionId: String, step: Int, stepName: String, customData: Table) -> void
记录指定玩家在某个漏斗中的步骤事件，包含漏斗名、漏斗会话标识、步骤序号、步骤名与附加数据。
| 参数 | 类型 | 说明 |
|---|---|---|
player | Player | 玩家对象（事件归属，必须在当前 Space 内） |
funnelName | String | 漏斗名称（非空，≤50 字符，仅允许 [a-zA-Z0-9_]） |
funnelSessionId | String | 漏斗会话ID（可选，≤50 字符） |
step | Int | 步骤编号（整数 1-100） |
stepName | String | 步骤名称（可选，≤50 字符） |
customData | Table | 自定义数据（key 仅限 CustomField01/02/03；value 支持 str/int/float/bool，str≤256 且不含逗号、引号、换行符） |
返回值 void
示例代码
上报业务提供的漏斗步骤
lua
-- @runtime server
local analyticsService = game:GetService("AnalyticsService")
local function reportFunnelStep(player, funnelName, sessionId, step, stepName)
if player == nil or funnelName == nil or sessionId == nil then return end
analyticsService:LogFunnelStepEvent(
player, funnelName, sessionId, step, stepName,
{ CustomField01 = "server" }
)
end
-- 由业务流程传入真实漏斗名、当前会话 ID、步骤编号和步骤名LogProgressionEvent
签名：LogProgressionEvent(player: Player, progressionPathName: String, status: String, level: Any, levelName: String, customData: Table) -> void
记录指定玩家沿某条进度路径的通用进度事件，包含路径名、状态、关卡标识、关卡名与附加数据。
| 参数 | 类型 | 说明 |
|---|---|---|
player | Player | 玩家对象（事件归属，必须在当前 Space 内） |
progressionPathName | String | 进度路径名称（非空，≤50 字符，仅允许 [a-zA-Z0-9_]） |
status | String | 状态（仅 Start / Complete / Fail） |
level | Any | 关卡（number 或 string；string ≤50 字符） |
levelName | String | 关卡名称（可选，≤50 字符） |
customData | Table | 自定义数据（progression 事件允许任意 key；value 支持 str/int/float/bool，str≤256 且不含 , " \r \n） |
返回值 void
示例代码
记录玩家的关卡进度事件
lua
-- @runtime server
local analyticsService = game:GetService('AnalyticsService')
local Players = game:GetService('Players')
for _, player in ipairs(Players:GetPlayers()) do
analyticsService:LogProgressionEvent(
player, 'TowerClimb', 'Complete', 3, '顶层',
{ score = 100, duration = 42 }
)
print('已上报关卡进度:', player:GetName())
endLogProgressionStartEvent
签名：LogProgressionStartEvent(player: Player, progressionPathName: String, level: Any, levelName: String, customData: Table) -> void
记录指定玩家沿某条进度路径的进度开始事件，包含路径名、关卡标识、关卡名与附加数据。
| 参数 | 类型 | 说明 |
|---|---|---|
player | Player | 玩家对象（事件归属，必须在当前 Space 内） |
progressionPathName | String | 进度路径名称（非空，≤50 字符，仅允许 [a-zA-Z0-9_]） |
level | Any | 关卡（number 或 string；string ≤50 字符） |
levelName | String | 关卡名称（可选，≤50 字符） |
customData | Table | 自定义数据（progression 事件允许任意 key；value 支持 str/int/float/bool，str≤256 且不含 , " \r \n） |
返回值 void
示例代码
上报业务提供的进度开始事件
lua
-- @runtime server
local analyticsService = game:GetService("AnalyticsService")
local function reportProgressStart(player, progressionPathName, level, levelName)
if player == nil or progressionPathName == nil or levelName == nil then return end
analyticsService:LogProgressionStartEvent(player, progressionPathName, level, levelName, nil)
endLogProgressionCompleteEvent
签名：LogProgressionCompleteEvent(player: Player, progressionPathName: String, level: Any, levelName: String, customData: Table) -> void
记录指定玩家沿某条进度路径完成关卡的事件，包含路径名、关卡标识、关卡名与附加数据。
| 参数 | 类型 | 说明 |
|---|---|---|
player | Player | 玩家对象（事件归属，必须在当前 Space 内） |
progressionPathName | String | 进度路径名称（非空，≤50 字符，仅允许 [a-zA-Z0-9_]） |
level | Any | 关卡（number 或 string；string ≤50 字符） |
levelName | String | 关卡名称（可选，≤50 字符） |
customData | Table | 自定义数据（progression 事件允许任意 key；value 支持 str/int/float/bool，str≤256 且不含 , " \r \n） |
返回值 void
示例代码
上报业务提供的进度完成事件
lua
-- @runtime server
local analyticsService = game:GetService("AnalyticsService")
local function reportProgressComplete(player, progressionPathName, level, levelName)
if player == nil or progressionPathName == nil or levelName == nil then return end
analyticsService:LogProgressionCompleteEvent(player, progressionPathName, level, levelName, nil)
endLogProgressionFailEvent
签名：LogProgressionFailEvent(player: Player, progressionPathName: String, level: Any, levelName: String, customData: Table) -> void
记录指定玩家沿某条进度路径的进度失败事件，包含路径名、关卡标识、关卡名与附加数据。
| 参数 | 类型 | 说明 |
|---|---|---|
player | Player | 玩家对象（事件归属，必须在当前 Space 内） |
progressionPathName | String | 进度路径名称（非空，≤50 字符，仅允许 [a-zA-Z0-9_]） |
level | Any | 关卡（number 或 string；string ≤50 字符） |
levelName | String | 关卡名称（可选，≤50 字符） |
customData | Table | 自定义数据（progression 事件允许任意 key；value 支持 str/int/float/bool，str≤256 且不含 , " \r \n） |
返回值 void
示例代码
上报业务提供的进度失败事件
lua
-- @runtime server
local analyticsService = game:GetService("AnalyticsService")
local function reportProgressFailure(player, progressionPathName, level, levelName, failReason)
if player == nil or progressionPathName == nil or levelName == nil then return end
analyticsService:LogProgressionFailEvent(player, progressionPathName, level, levelName, { failReason = failReason })
endGetPlayerSegmentsAsync
签名：GetPlayerSegmentsAsync(player: Player) -> Table (分段数据：HasData(bool)；ActivePayerStatus(Top15Percent/Intermediate35Percent/Casual50Percent/Never/Lapsed/Unknown)；WhenUserFirstPlayed(Days0To30/Days31To90/Days91To180/Days181To365/Days366Plus/Unknown)；PlayerPlatformSpenderStatus(Active/OtherPayer/Unknown))
在协程中异步查询指定玩家的分段数据，返回 Table；HasData 表示是否存在分段数据，其余字段包括 ActivePayerStatus、WhenUserFirstPlayed 与 PlayerPlatformSpenderStatus。
| 参数 | 类型 | 说明 |
|---|---|---|
player | Player | 玩家对象（必须在当前 Space 内） |
返回值 Table (分段数据：HasData(bool)；ActivePayerStatus(Top15Percent/Intermediate35Percent/Casual50Percent/Never/Lapsed/Unknown)；WhenUserFirstPlayed(Days0To30/Days31To90/Days91To180/Days181To365/Days366Plus/Unknown)；PlayerPlatformSpenderStatus(Active/OtherPayer/Unknown))
示例代码
在任务协程中查询玩家分段
lua
-- @runtime server
local analyticsService = game:GetService('AnalyticsService')
local Players = game:GetService('Players')
local Task = game:GetService('Task')
local player = Players:GetPlayers()[1]
if player == nil then return end
Task:Spawn(function()
local segments = analyticsService:GetPlayerSegmentsAsync(player)
if segments == nil then return end
print('是否有分段数据:', segments.HasData)
print('付费分层:', segments.ActivePayerStatus)
end)LogTrackDataChange
签名：LogTrackDataChange(player: Player, eventName: String, changeNum: Float, attrKeys?: Table) -> void
记录指定玩家的自定义蛋码埋点，提交事件名、数据变化量，并可选地附带玩家属性键列表。
| 参数 | 类型 | 说明 |
|---|---|---|
player | Player | 玩家对象（事件归属，必须在当前 Space 内） |
eventName | String | 事件名称（非空，1-12 字符，直接作为蛋码 data_name 上报） |
changeNum | Float | 数据变化量 |
attrKeys? | Table | 可选附带的玩家属性 key 列表（string[]）；通过 player.Character:GetAttribute(key) 读取，读不到的 key 自动忽略 |
返回值 void
示例代码
记录玩家数据变化
lua
-- @runtime server
local analyticsService = game:GetService('AnalyticsService')
local Players = game:GetService('Players')
Players.PlayerAdded:Connect(function(player)
analyticsService:LogTrackDataChange(player, 'QuestGain', 1)
end)