You've already forked CC-Framework.BriskGameServer
Initial Brisk Unity SDK project
This commit is contained in:
226
服务参考_临时/Brisk Unity SDK接入文档.md
Normal file
226
服务参考_临时/Brisk Unity SDK接入文档.md
Normal file
@@ -0,0 +1,226 @@
|
||||
# Brisk Unity SDK接入文档
|
||||
|
||||
## 1. 这份文档适合做什么
|
||||
|
||||
这份文档用于在 Unity 侧封装 Brisk SDK。
|
||||
|
||||
建议把 SDK 拆成以下层次：
|
||||
|
||||
- `BriskClient`
|
||||
- `BriskAuth`
|
||||
- `BriskConfig`
|
||||
- `BriskAnnouncements`
|
||||
- `BriskRanks`
|
||||
- `BriskArchives`
|
||||
- `BriskSpaces`
|
||||
|
||||
## 2. 初始化模型
|
||||
|
||||
Unity 客户端初始化建议持有：
|
||||
|
||||
- `baseUrl`
|
||||
- `gameKey`（必填）
|
||||
- `clientVersion`（推荐传入；服务端接口当前可选，但会影响版本命中）
|
||||
- `deviceId`（推荐传入；`bootstrap` 接口当前可选）
|
||||
|
||||
不再需要项目级 `channel / platform`。
|
||||
|
||||
示例：
|
||||
|
||||
```csharp
|
||||
var options = new BriskOptions {
|
||||
BaseUrl = "https://brisk.lightyears.ltd",
|
||||
GameKey = "demo-game",
|
||||
ClientVersion = Application.version,
|
||||
DeviceId = SystemInfo.deviceUniqueIdentifier
|
||||
};
|
||||
```
|
||||
|
||||
## 3. 登录模型
|
||||
|
||||
登录属于独立模块，不属于初始化参数。
|
||||
|
||||
Unity 登录接口建议统一成：
|
||||
|
||||
```csharp
|
||||
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. 空间跳转建议
|
||||
|
||||
如果排行榜头像点击来自第三方平台，推荐直接支持：
|
||||
|
||||
```csharp
|
||||
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 / 登录态失效
|
||||
- 维护模式
|
||||
- 玩家被封禁
|
||||
- 存档版本冲突
|
||||
|
||||
建议统一抛出：
|
||||
|
||||
```csharp
|
||||
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](/F:/OtherWork/BriskGameSerivce/Brisk%20API%E6%8E%A5%E5%8F%A3%E4%B8%8E%E7%A4%BA%E4%BE%8B%E6%96%87%E6%A1%A3.md)
|
||||
- OpenAPI：
|
||||
- [openapi.yaml](/F:/OtherWork/BriskGameSerivce/openapi.yaml)
|
||||
Reference in New Issue
Block a user