跳到主要内容
快速开始

本页尚未翻译,当前显示英文版本。

连接与 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 窗口会自动填写;在代码中配置时必填。
GameVersion1.0.0你的 build 版本,原样发送。
EnableAutomaticPlayerAuthentication开启连接时自动以匿名 Player 登录。
AnonymousDisplayName—新建匿名 Player 的显示名称。
PlayerSessionStorePlayerPrefs两次启动之间 Player 的 Session 保存在哪里,参见 Token 与刷新。
KeepAlivePingIntervalMs · KeepAlivePongTimeoutMs30000 · 10000平台期望的检测间隔,以及等待响应的时长。
TimeoutSeconds120单个请求的超时时间。
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
SessionRevokedSession 被吊销,例如在 Players 中操作。是
SessionMergedPlayer 的账号被合并到另一个账号。是
RefreshRejected平台拒绝续期 Session。是
ExpiredWithoutRefreshtoken 已过期,且未能及时续期。是
BannedPlayer 被封禁。否
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平台正在维护,拒绝连接。

后续步骤

更新于 2026年10月19日