CC-Framework.BriskGameServer/服务参考_临时/Brisk Unity SDK接入文档.md

Brisk Unity SDK接入文档

1. 这份文档适合做什么

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

建议把 SDK 拆成以下层次：

• BriskClient
• BriskAuth
• BriskConfig
• BriskAnnouncements
• BriskRanks
• BriskArchives
• BriskSpaces

2. 初始化模型

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

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

不再需要项目级 channel / platform。

示例：

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. 推荐接入顺序

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

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. 玩家空间模块建议

玩家空间适合承载公开展示数据，不建议放主存档。

推荐放：

• 简介文本
• 头像展示字段
• 成就展示摘要
• 公开资料卡

当前接口核心是：

• UpdateMySpaceAsync(payloadJson)
• GetSpaceByPlayerIdAsync(playerId)
• GetSpaceByLoginIdentityAsync(loginProvider, loginUserId)
• LikeSpaceAsync(playerId)
• LikeSpaceByLoginIdentityAsync(loginProvider, loginUserId)
• GetMyVisitsAsync(limit)

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 至少要覆盖：

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

13. 配套文件

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