SDK 初始化与 Handshake

最后更新：2026 年 7 月 16 日

SDK 初始化是 PlayServ 准备运行时上下文的过程，这个上下文是启动 Session、进入可供 gameplay 功能使用的状态所必需的。它包括：

• 收集必需的配置输入项
• 通过 PlayServ.Ready(...) 确立客户端就绪
• 通过 PlayServ.Server.Ready() 确立服务端就绪

信息

在以下情况下使用这个流程：

• 在应用启动时开启一个 Session
• 通过 Ready(UserToken) 在 Session 一开始就完成认证，或在运行过程中稍后再认证
• 确保服务端运行时在客户端加入之前已经就绪

---

开始之前

SDK 初始化需要在 PlayServ Backoffice 中配置好 Project 和凭据。如果你还没做过，请先完成下面这些步骤。

1

在 Backoffice 中创建 Project

打开 PlayServ Backoffice，创建一个新的 Project。你会得到一个 Game ID —— 这是配置 SDK 时需要用到的 Project 标识符。

创建 Project 时还会自动生成一个 Development Environment，接入期间你就在这里工作。

Creating a New Project →

2

生成 Game Access Token

在 Project 工作区中打开 SDK Keys 一节，生成一个 Development key。它就是你的 Game Access Token —— SDK 用它连接到正确的 Project Environment。

请妥善保管。key 的完整值只在创建的那一刻显示一次。

API Key Management →

3

把 Project 连接到 Unity

导入 PlayServ 的 Unity 包，打开 PlayServ 设置窗口，填入前面几步得到的 Game Access Token 和 Game ID。

之后，SDK 就能从 PlayServ 的 config asset 中解析出 Project 配置。

Connecting a Project to Unity →

---

配置输入项

PlayServ 建立一个 Session 需要四项输入。其中三项由系统自动管理 —— 只有 Game Access Token 需要开发者自己配置。

输入项	来源	由谁管理
GameAccessToken	在 Unity 的 PlayServ 设置窗口中配置	开发者
UserDeviceToken	由 SDK 自动生成并持久化	SDK
GameVersion	由 SDK 在后台从 Backoffice 同步	SDK
Client SDK Version	从已安装的 SDK 包中确定	SDK

Game Access Token 是与 Environment 绑定的凭据，用于标识游戏上下文并校验连接。它在 Unity Editor 的 PlayServ 设置窗口中设置，作用域是某个具体的 Project Environment —— Development 或 Production。

生成和轮换 token 的方法见 API Key Management。

备注

PlayServ 把网络原语封装了起来。在客户端代码中，你响应的是 Session 状态和 SDK API，而不是自己管理底层的连接与断开。

---

客户端初始化

客户端代码中不需要显式初始化。SDK 会自动准备好内部组件，并把 Session 置于初始的 Offline 状态。

客户端通过下面这行来表明自己已就绪：

await PlayServ.Ready();

如果设备上已经存有 UserToken，可以直接传进去，让 Session 以已认证的状态启动：

await PlayServ.Ready(UserToken);

这会进入 handshake 流程，让 Session 得以向 Active 推进。

---

服务端初始化

在客户端能够加入之前，game server 要先完成自身的启动，并显式调用 PlayServ.Server.Ready()。

[Server]
class GameServer
{
    GameServer()
    {
        InitializeAsync();
    }

    private async Task InitializeAsync()
    {
        await Something();
        PlayServ.Server.Ready();
    }
}

注意

如果某个服务端 RPC 类中包含对 Ready() 的调用，代码分析器就会预期 Ready() 至少被执行一次。在那之前，服务端不会被视为可用。

---

服务端启动配置（可选）

如果服务端代码在启动时需要配置，可以把配置存成一个 Singleton Entity，并在服务端启动时通过数据模型 API 取回。

[Server]
class GameServer
{
    private readonly Task<Model> _configTask;

    public GameServer()
    {
        _configTask = LoadConfigurationAsync();
    }

    private async Task<Model> LoadConfigurationAsync()
    {
        return await PlayServ.GetServerConfig();
    }

    public async Task DoSomethingNext()
    {
        var config = await _configTask;
        config.StartingLevel; // 1
    }
}

备注

服务端的 build 版本管理由 Version Module 负责，不需要开发者手动对齐。

---

下一步

• Proxy Module & Handshake —— 调用 Ready(...) 之后发生了什么
• Session Lifecycle & States —— Offline / Recovering / Active / Banned
• User Login & Authentication —— Ready(UserToken)、Login(UserToken) 与 ValidateClient