线上运营(Live operations)
import "github.com/nsgo-dev/game/packages/game/liveops"
liveops 为 NSGo 游戏提供与具体服务商无关的线上运营基础能力。它只依赖 Go 标准库、packages/game 和 NSGo 的公开 core API,不内置任何第三方崩溃上报、埋点分析或广告 SDK。
范围决策(#194)
| 能力 | 状态 | 说明 |
|---|---|---|
| 崩溃报告(#195) | 纳入范围 | 与服务商无关的 panic 捕获,附带固定大小步长环形缓冲区、堆栈、元数据和可选状态快照。 |
| 统计分析(#198) | 纳入范围 | 与服务商无关、严格以显式同意为前提的事件 API,同意状态保存在 core.Storage。未显式同意前不会发送也不会缓存任何事件。 |
| 云存档(#196) | 纳入范围(接口) | 当前提供与平台无关的 CloudSync 接口;iCloud、Play Games、Steam Cloud 等内置适配器等待平台云存档绑定就绪。 |
| 广告(#199) | 不纳入核心层 | 广告网络(AdMob、AppLovin 等)依赖专有原生 SDK,并伴随繁重的商店政策与隐私合规义务,不放入核心 game 模块;需要广告的游戏可直接通过 NSGo 嵌入原生 SDK 视图。 |
崩溃报告
CrashReporter 用预分配的环形缓冲区保存最近若干次模拟步长(DefaultHistorySize = 120,稳态零堆分配),并为 game.Loop 回调或任意函数提供 panic 防护。
RecordStep(dt, summary)与RecordStepData(dt, summary, data)向环形缓冲区追加一条StepRecord并返回单调递增的步数。WrapLoop(l)返回带防护的*game.Loop;GuardLoop(l)原地包装l.Update和l.Draw。如果Update在单步内未自行调用RecordStep,防护层会自动记录一条"update"步长(包含触发 panic 的那一步)。RunSafe(fn)防护任意回调并报告是否发生 panic。- 发生 panic 时,报告器构造可 JSON 序列化的
CrashReport(包含Timestamp、Panic、Message、Stack、Step、按时间从旧到新排列的LastSteps、来自CaptureState的可选State以及Metadata副本),并交给Reporter。 - 需要上报后继续抛出 panic 时,可设置
Rethrow: true。
reporter := liveops.NewCrashReporter(liveops.CrashOptions{
HistorySize: 120,
Reporter: func(r liveops.CrashReport) { uploadOrSave(r) },
CaptureState: func() any { return world.Snapshot() },
Metadata: map[string]string{"version": appVersion, "scene": "level-1"},
Now: cx.Now,
})
loop := reporter.WrapLoop(&game.Loop{
Update: func(dt time.Duration) {
reporter.RecordStep(dt, "world.step")
world.Step(dt)
},
Draw: func(alpha float64) { world.Draw(alpha) },
})
loop.Run(cx)
统计分析
Analytics 要求玩家显式同意(ConsentGranted)后才分发任何事件,且不内置任何第三方埋点后端。
- 同意状态为
ConsentUnknown(默认)、ConsentDenied和ConsentGranted。 NewAnalytics(store, key, provider)把同意状态持久化到core.Storage的key下(为空时使用DefaultConsentKey);缺失或无法识别的值一律按默认关闭处理(ConsentUnknown)。NewMemoryAnalytics(provider)仅在内存中保存状态。- 处于
ConsentUnknown或ConsentDenied时,Track(name, props)直接丢弃事件并返回false,绝不发送,也不缓存供后续补发。 - 处于
ConsentGranted时,Track对props做防御性拷贝,并通过AnalyticsProvider.Send分发Event。 - 调用
SetConsent(ConsentDenied)撤回同意后,所有后续Track和Flush调用会立即停止。
analytics := liveops.NewAnalytics(cx.Storage(), "liveops.consent", myProvider)
analytics.SetClock(cx.Now)
// 未显式同意前直接丢弃:
analytics.Track("app_open", nil) // 返回 false,发送 0 条事件
// 玩家同意后:
_ = analytics.SetConsent(liveops.ConsentGranted)
analytics.Track("level_complete", map[string]any{"level": 1})
云存档
CloudSync 定义了与服务商无关的存档槽位接口(Load、Save、Delete、List,以及 ErrSlotNotFound 和 ErrCloudUnavailable 哨兵错误)。游戏目前可以针对自有后端或内存测试替身实现该接口;iCloud、Google Play Games 和 Steam Cloud 的平台适配器等待平台云存档绑定就绪(#196)。