foldcc/CC-Framework.BriskGameServer

Fork 0

Files

CORE-FOLDCC\Core a257a8a912 更新文档

2026-04-11 15:51:08 +08:00

6.1 KiB

Raw Blame History

Brisk Unity SDK接入文档

1. 这份文档适合做什么

这份文档用于在 Unity 侧封装 Brisk SDK。

建议把 SDK 拆成以下层次：

BriskTime
BriskClient
BriskAuth
BriskConfig
BriskAnnouncements
BriskRanks
BriskArchives
BriskSpaces

2. 初始化模型

Unity 客户端初始化建议持有：

baseUrl
gameKey（必填）
clientVersion（推荐传入；服务端接口当前可选，但会影响版本命中）
deviceId（推荐传入；bootstrap 接口当前可选）

不再需要项目级 channel / platform。

如果只是做平台授时，不需要传 gameKey，可以单独调用时间接口。

示例：

var options = new BriskOptions {
    BaseUrl = "https://brisk.lightyears.ltd",
    GameKey = "demo-game",
    ClientVersion = Application.version,
    DeviceId = SystemInfo.deviceUniqueIdentifier
};

3. 登录模型

登录属于独立模块，不属于初始化参数。

Unity 登录接口建议统一成：

Task<LoginResult> LoginAsync(
    string loginProvider,
    string loginUserId = null,
    string code = null,
    string nickname = null,
    string avatarUrl = null,
    Dictionary<string, object> profileJson = null
)

说明：

loginProvider：如 tap
loginUserId：平台返回的稳定唯一用户 ID
code：如果平台走 code 兑换模式则传这个
loginUserId 和 code 二选一
nickname / avatarUrl / profileJson 为可选同步资料

4. 推荐接入顺序

可选：SyncServerTimeAsync()
BootstrapAsync()
从第三方 SDK 获取：
- loginProvider
- loginUserId 或 code
- 可选昵称、头像、扩展资料
LoginAsync(...)
保存 accessToken
拉取：
- GetMeAsync()
- GetCurrentConfigAsync()
- ListAnnouncementsAsync()
进入业务模块

平台授时接口建议封装：

Task<ServerTimeResult> SyncServerTimeAsync()

建议返回：

ServerTime
ServerUnix
ServerUnixMs

5. 身份模型建议

Unity SDK 内建议同时保存两套身份：

外部身份：
- LoginProvider
- LoginUserId
内部身份：
- PlayerId
- ProjectAccountId

原因：

跨系统跳转、和第三方 SDK 共存时，外部身份更方便
游戏内高频接口仍以内部 player_id 为主更自然

6. 空间跳转建议

如果排行榜头像点击来自第三方平台，推荐直接支持：

Task<SpaceInfo> GetSpaceByLoginIdentityAsync(string loginProvider, string loginUserId)
Task<SpaceStats> GetSpaceStatsByLoginIdentityAsync(string loginProvider, string loginUserId)
Task LikeSpaceByLoginIdentityAsync(string loginProvider, string loginUserId)

这样可以避免 Unity 侧先做一次平台 ID 到 Brisk player_id 的映射查询。

7. 排行榜模块建议

客户端侧建议封装：

GetRankTopAsync(rankKey, limit)
GetRankMeAsync(rankKey)
GetRankAroundMeAsync(rankKey, range)
SubmitScoreAsync(rankKey, score)
GetCurrentSeasonAsync(rankKey)
GetSeasonHistoryAsync(rankKey, limit)
GetSeasonHistoryDetailAsync(rankKey, seasonId, limit)

榜单项需要暴露：

Rank
PlayerId
ProjectAccountId
LoginProvider
LoginUserId
Score
Nickname
AvatarUrl

8. 云存档模块建议

云存档适合承载真实游戏数据。

原因：

上传下载是二进制流
天然适配 bytes
可直接存：
- JSON bytes
- protobuf bytes
- msgpack bytes
- 压缩后的存档二进制

Unity SDK 建议提供：

GetArchiveSlotsAsync()
GetArchiveMetaAsync(slotNo)
UploadArchiveAsync(slotNo, baseVersion, checksum, byte[])
DownloadArchiveAsync(slotNo)

9. 玩家空间模块建议

玩家空间适合承载公开展示数据或空间自定义内容，不再限制为 JSON。

推荐放：

简介文本
头像展示字段
成就展示摘要
公开资料卡
小型二进制空间内容
文本、JSON、protobuf、msgpack 等自定义格式

当前接口核心是：

UploadMySpaceContentAsync(baseVersion, contentType, checksum, byte[])
DownloadSpaceContentByPlayerIdAsync(playerId)
DownloadSpaceContentByLoginIdentityAsync(loginProvider, loginUserId)
GetSpaceByPlayerIdAsync(playerId)
GetSpaceByLoginIdentityAsync(loginProvider, loginUserId)
LikeSpaceAsync(playerId)
LikeSpaceByLoginIdentityAsync(loginProvider, loginUserId)
GetMyVisitsAsync(limit)

建议 SDK 暴露两层模型：

空间主信息：
- ContentExists
- ContentVersion
- ContentType
- ContentSizeBytes
- ContentChecksum
- LikeCount
- VisitCount
空间内容本体：
- 原始 byte[]
- 下载响应头中的 X-Space-Version
- 下载响应头中的 X-Space-Checksum

如果上层业务实际保存的是文本或 JSON，建议仍按 byte[] 统一收发，再由业务层自己决定如何编码和反序列化。

10. 动态配置建议

动态配置拆为两层：

feature_flags
- 适合直接做开关或 key-value 判断
dynamic_config
- 适合结构化配置对象

Unity SDK 可以考虑：

把 feature_flags 映射成 Dictionary<string, object>
把 dynamic_config 保留原始 JSON，并允许上层自行反序列化

11. 错误与登录态处理

SDK 需要统一处理：

HTTP 非 2xx
业务码非 0
401 / 登录态失效
维护模式
玩家被封禁
存档版本冲突

建议统一抛出：

public sealed class BriskApiException : Exception {
    public int HttpStatus { get; }
    public int Code { get; }
    public string ServerMessage { get; }
}

12. Unity 侧最小落地清单

第一版 SDK 至少要覆盖：

初始化
登录换票
登录态保存
玩家信息读取
动态配置读取
公告读取与已读
排行榜提交与读取
云存档上传下载
玩家空间读取、写入、点赞
按 login_provider + login_user_id 访问空间

13. 配套文件

API 总文档：
- Brisk API接口与示例文档.md
OpenAPI：
- openapi.yaml

6.1 KiB Raw Blame History Unescape Escape