本页尚未翻译,当前显示英文版本。
连接与 Session
游戏与 PlayServ 之间保持一条经过认证的实时连接。 PlayServ.Connect() 让 Player 登录、打开连接并保持连接:断线后自动重连,并自行刷新 Player 的 token。你的代码只需连接一次,留意 Session 丢失,并在游戏结束时断开连接。
using System;
using Playserv.Wrapper;
using UnityEngine;
public sealed class PlayServBootstrap : MonoBehaviour
{
async void Start()
{
PlayServAuth.SessionLost += info => Debug.LogWarning($"Session lost: {info.Reason}");
PlayServ.OnTransportError += error => Debug.LogWarning(error);
try
{
if (await PlayServ.Connect())
Debug.Log($"Online as {PlayServAuth.PlayerId}");
}
catch (Exception e) // signing in failed, for example a revoked client key
{
Debug.LogError(e.Message);
}
}
void OnDestroy() => PlayServ.Disconnect();
}
SDK 的安装和配置参见 连接你的游戏。
SDK 需要什么
Connect() 读取你在 PlayServ 窗口中设置的配置。如果要改为在代码中配置,请在 Connect() 之前调用 PlayServ.Config(...)。
| 设置 | 默认值 | 含义 |
|---|---|---|
ClientToken | — | Project 的 client key(pk_…),用于选择 Project 和 Environment。必填。 |
BackendServerAddress | — | 平台地址 wss://platform.playserv.com/ws。PlayServ 窗口会自动填写;在代码中配置时必填。 |
GameVersion | 1.0.0 | 你的 build 版本,原样发送。 |
EnableAutomaticPlayerAuthentication | 开启 | 连接时自动以匿名 Player 登录。 |
AnonymousDisplayName | — | 新建匿名 Player 的显示名称。 |
PlayerSessionStore | PlayerPrefs | 两次启动之间 Player 的 Session 保存在哪里,参见 Token 与刷新。 |
KeepAlivePingIntervalMs · KeepAlivePongTimeoutMs | 30000 · 10000 | 平台期望的检测间隔,以及等待响应的时长。 |
TimeoutSeconds | 120 | 单个请求的超时时间。 |
PlayServ.Config(new PlayServSettings
{
ClientToken = "pk_...",
GameVersion = "1.0.0",
BackendServerAddress = "wss://platform.playserv.com/ws",
});
client key 决定 Environment
client key 决定游戏与哪个 Project 的哪个 Environment 通信。如果游戏能连接却看不到你的任何数据,通常是用了其他 Environment 的 key。client key 可以安全地打包进 build;server key 则绝对不行,参见 API key 管理。
连接
让 Player 登录
SDK 会恢复保存在这台设备上的 Player,或新建一个匿名 Player。要让 Player 通过登录提供方登录,参见 用户登录。
打开连接
SDK 打开连接,并用 client key 和 Player 的 token 表明身份。平台会校验这两者。
上 线
平台接受后,状态变为 Online,保活开始,Connect() 返回 true。如果连接无法打开或被拒绝,它返回 false,状态回到 Offline,OnTransportError 会给出原因。如果在此之前 Player 登录就失败了(例如 client key 无效或已被吊销),Connect() 会抛出异常。
在主线程中调用 Connect(),只调用一次。连接过程中再次调用会返回同一个 task;已经在线时再调用会抛出异常。
连接状态
PlayServ.State 告诉你连接当前处于什么状态。状态变化没有对应的 Event:需要时直接读取。
| 状态 | 含义 |
|---|---|
| Offline | 未连接:Connect() 之前、Disconnect() 之后,或连接失败后。 |
| Connecting | 正在打开连接。 |
| Handshaking | 已连接,等待平台接受游戏和 Player。 |
| Online | 就绪。数据、Event 和 Function 调用都可以使用。 |
| Reconnecting | 连接已断开,SDK 正在恢复。 |
重连与保活
SDK 大约每 25 秒检测一次连接。如果平台 40 秒内没有响应,或连接断开,SDK 会自动重连:
| 尝试 | 时间 |
|---|---|
| 首次尝试 | 断线 2 秒后。 |
| 后续尝试 | 从 1 秒开始,每次翻倍,最长 30 秒。 |
| 每次尝试 | 30 秒后超时。 |
| 何时放弃 | 不会自行放弃:会一直尝试,直到成功或你调用 Disconnect()。 |
每次重连都会用新的 token 重新登录。如果在断线后 30 秒内重连成功,数据订阅会从中断处继续。如果平台主动结束连接(见下文),SDK 不会重连。
Token 与刷新
Player 的 access token 有效期为 15 分钟;SDK 会在过期前 90 秒原地续期,不会断开连接。续期凭据本身有效期为 30 天:Player 在上次 Session 之后 30 天内回来,会被直接重新登录。
Player 的 ID 和续期 token 保存在设备上,默认存放在 PlayerPrefs 中,按 client key 和平台分别保存。使用不同 client key 的 build 找不到已保存的 Player,会新建一个。PlayerPrefs 不是安全存储:正式上线的游戏应将 PlayerSessionStore 设为你自己的 IPlayServPlayerSessionStore 实现,把这些数据存放在安全的地方。
Session 丢失时
平台可能会结束 Session:Player 被封禁、Session 被吊销,或账号被合并。 此时连接被关闭,SDK 清除已保存的 Session 并断开连接,PlayServAuth.SessionLost 触发一次。
PlayServAuth.SessionLost += info =>
{
if (info.CanRetry) ShowSignIn(); // sign in again, then Connect()
else ShowBlocked(info.Reason); // don't retry
};
| 原因 | 何时发生 | CanRetry |
|---|---|---|
SessionRevoked | Session 被吊销,例如在 Players 中操作。 | 是 |
SessionMerged | Player 的账号被合并到另一个账号。 | 是 |
RefreshRejected | 平台拒绝续期 Session。 | 是 |
ExpiredWithoutRefresh | token 已过期,且未能及时续期。 | 是 |
Banned | Player 被封禁。 | 否 |
CredentialRevoked | 游戏使用的 client key 已被吊销。 | 否 |
封禁或 key 被吊销时不要重试
当 CanRetry 为 false 时,再次连接 也会以同样的方式失败。请告知 Player;如果是 key 被吊销,请发布一个使用有效 key 的 build。
你自己退出登录时,SessionLost 不会触发。
错误
| Event | 触发场景 |
|---|---|
PlayServ.OnTransportError | 连接问题:连接被拒绝或中断,或平台断开了游戏的连接。 |
PlayServ.OnError | 不属于某次具体调用的错误。具体调用的错误会随该调用的结果返回。 |
| 代码 | 含义 |
|---|---|
00001 | 平台拒绝了连接:client key 或 Player 的 token 无效,或缺少必需的信息。 |
02004 | 需要 Player Session,但游戏连接时没有提供。 |
02003 | 平台断开了游戏的连接。 |
01002 | 此 SDK 版本已不再受支持:请更新 SDK。 |
01003 | 此游戏版本不被接受:请更新游戏。 |
02001 | 平台已达到连接数上限,请稍后重试。 |
02002 | 平台正在维护,拒绝连接。 |
后续步骤
- 用户登录 —— 让 Player 使用 Apple、Google、Facebook、Epic 或 Steam 登录
- 连接你的游戏 —— 安装并配置 SDK
- API key 管理 —— 游戏使用的 client key
更新于 2026年10月19日