foldcc/CC-Framework.BriskGameServer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
07fc690e67faafc2765094d613dfa0e4afad5adc
CC-Framework.BriskGameServer/服务参考_临时/Brisk Unity SDK接入文档.md

6.9 KiB
Raw Blame History

Brisk Unity SDK接入文档

1. 这份文档适合做什么

这份文档用于说明当前 Brisk Unity SDK 的接入结构与推荐调用方式。

当前 SDK 已采用静态总入口：

  • Brisk.InitializeAsync(...)
  • Brisk.Auth.xxx
  • Brisk.Player.xxx
  • Brisk.Config.xxx
  • Brisk.Announcements.xxx
  • Brisk.Leaderboard.xxx
  • Brisk.Archive.xxx
  • Brisk.Space.xxx

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
    • 压缩后的存档二进制

当前 SDK 已提供：

  • GetArchiveSlotsAsync()
  • GetArchiveMetaAsync(slotNo)
  • UploadAsync(slotNo, byte[], baseVersion, checksum)
  • UploadTextAsync(slotNo, text, baseVersion, checksum)
  • UploadJsonAsync(slotNo, payload, baseVersion, checksum)
  • DownloadArchiveAsync(slotNo)
  • DownloadTextAsync(slotNo)
  • DownloadJsonAsync(slotNo)

推荐上层使用策略：

  • 文本存档：优先直接用 UploadTextAsync / DownloadTextAsync
  • JSON 存档：优先直接用 UploadJsonAsync / DownloadJsonAsync
  • 二进制存档：继续用 UploadAsync / DownloadAsync

其中：

  • SDK 会自动计算上传用 checksum
  • 手动传 checksum 时也可以带 sha256: 前缀，SDK 会自动归一化

9. 玩家空间模块建议

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

推荐放：

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

当前 SDK / 接口核心是：

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

当前 SDK 额外提供了一个极简便捷入口：

  • Brisk.Space.UpdateMyAsync(payload, baseVersion, contentType, checksum)

它的行为是：

  • payload 为 string 时，自动按 text/plain 上传
  • payload 为 byte[] 时，自动按 application/octet-stream 上传
  • payload 为其他对象时，自动序列化为 JSON 并按 application/json 上传

建议 SDK 暴露两层模型：

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

如果上层业务追求最省事，可以直接用 UpdateMyAsync(string) 或 UpdateMyAsync(object)； 如果业务自己管理编码、压缩、protobuf、msgpack 等格式，则继续走 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 至少要覆盖：

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

13. 配套文件

Reference in New Issue View Git Blame Copy Permalink