本页尚未翻译,当前显示英文版本。
用户登录
每个玩家都从匿名 Player 开始,想保留账号时再通过提供方登录。 PlayServ.Connect() 在首次启动时创建匿名 Player,之后每次启动都会恢复它。随后通过 Apple、Google、Facebook、Epic 或 Steam 登录,会把该提供方关联到同一个 Player 上,玩家以游客身份取得的一切都不会丢失。
using Playserv.Identity;
using Playserv.Wrapper;
using UnityEngine;
// After PlayServ.Connect(): attach Google to the current player.
var result = await PlayServAuth.LoginExternalAsync(PlayServExternalIdentityProof.FromGoogleIdToken(idToken));
if (result.Status == PlayServAuthOperationStatus.Success)
Debug.Log($"Signed in as {PlayServAuth.PlayerId}");
玩家可用的提供方在 SSO & Auth 中为 Project 开启。
匿名 Player
游戏用客户端密钥连接时,SDK 会让一个匿名 Player 登录:首次启动时新建,之后使用保存下来的那个,无需其他操作。会话如何保持,见 Connection & Session。
| 属性 | 含义 |
|---|---|
PlayServAuth.IsLoggedIn | 是否有 Player 已登录。 |
PlayServAuth.PlayerId | Player 的 PlayServ ID,形如 plr_…。添加提供方后保持不变。 |
PlayServAuth.SessionKind | 匿名时为 Anonymous,关联提供方后为 Registered,登 录前为 None。 |
PlayServAuth.CurrentSession.LinkedProviders | 已关联到该 Player 的提供方。 |
要给新的匿名 Player 命名(包括退出登录后新建的那个),在连接之前通过代码设置 SDK 设置中的 AnonymousDisplayName。它不会重命名已有的 Player。
通过提供方登录
从提供方拿到玩家的 token,转换成凭证(proof),再传给 LoginExternalAsync。
| 提供方 | 凭证 | 配套包 |
|---|---|---|
| Apple | FromAppleIdToken(idToken, nonce) | com.playserv.apple-signin,使用 iOS 上的 Sign in with Apple |
FromGoogleIdToken(idToken, nonce) | com.playserv.google-signin,基于 Google Sign-In plugin for Unity | |
FromFacebookLimitedLoginToken(token, nonce);nonce 必填 | com.playserv.facebook-login,使用 Meta SDK 的 Limited Login | |
| Epic | FromEpicExternalAuthToken(token) | com.playserv.epic-auth,使用 EOS plugin for Unity |
| Steam | FromSteamTicket(ticket) | com.playserv.steam-auth,使用 Steamworks.NET |
配套包是可选的辅助工具,用来替你获取提供方的 token;你也可以用手头已有的 token 自行构建凭证。在 Tools ▸ PlayServ ▸ Settings 的 SDK 模块设置中安装并开启它们。在凭证上加 .WithDisplayName(name),可以在账号首次创建或关联时为 Player 命名。
LoginExternalAsync(proof, mode) 决定当前匿名 Player 的去向。mode 的类型是 PlayServExternalLoginMode:
| 模式 | 适用场景 | 结果 |
|---|---|---|
PreserveCurrentPlayer(默认) | 玩家在一直在玩的设备上登录。 | 提供方关联到当前 Player,其 ID 和进度保持不变。 |
RecoverProviderAccount | 玩家在新设备上恢复账号。 | 拥有该提供方账号的 Player 取代匿名 Player。 |
结果的 Status 为 Success、Conflict 或 Failed。冲突表示该提供方账号已属于另一个 Player:当前 Player 保持不变,result.Conflict 描述另一个 Player,你可以让玩家选择合并或切换。登录成功后,游戏会用新会话重新连接。
PlayServAuth.GetProvidersAsync() 列出所有提供方及其 Enabled 和 Available 标记;在登录界面上展示可用的那些即可。
通过浏览器登录
PlayServAuth.LoginBrowserAsync(provider, options) 在提供方自己的网页上让玩家登录,适用于 WebGL、桌面 build 和 Editor。WebGL 会打开弹窗,桌面和 Editor 则打开系统浏览器。SDK 最多等待 5 分钟让玩家完成登录。
| 规则 | 原因 |
|---|---|
| 在 WebGL 中,直接在点击处理器里调用。 | 否则浏览器会拦截弹窗,结果为 BrowserPopupBlocked。 |
| 同一时间只运行一次浏览器登录。 | 第二次调用会返回 BrowserFlowInProgress。 |
设置 AllowPlayerSwitch = true 以允许切换 Player。 | 如果该提供方账号属于另一个 Player,除非允许切换,否则结果为 BrowserPlayerSwitchRequired。 |
浏览器登录从不关联或合并账号。
关联、解除关联与合并
| 调用 | 作用 |
|---|---|
LinkIdentityAsync(proof) | 为当前 Player 再关联一个提供方。每个提供方下,一个 Player 只有一个账号。 |
UnlinkIdentityAsync("google") | 移除一个提供方。最后一个提供方无法移除。 |
MergeIdentityAsync(conflict, choice, freshProof) | 把当前 Player 和冲突中的另一个 Player 合并为一个。choice 为 PlayServMergeChoice.KeepCurrentPlayer 或 UseConflictingPlayer;freshProof 是冲突提供方的一个新凭证。 |
合并转移的是登录方式,不是进度
被合并 Player 的提供方会转到保留下来的 Player 上。被合并 Player 的进度、购买和 Record 仍留在它自己名下,不会被复制。
Player 的资料
PlayServAuth.GetCurrentPlayerProfileAsync() 返回已登录 Player 自己的资料,只加载一次;RefreshCurrentPlayerProfileAsync() 会重新加载。
退出登录
PlayServAuth.LogoutAsync() 在平台上结束会话,清除设备上的会话,并让一个新的匿名 Player 登录。如果未能通知到平台,结果中的错误会说明这一点;无论如何,设备都会退出登录。
登录失败时
失败信息通过结果的 Error 返回。只有以下情况会抛出异常:取消、参数缺失或无效,以及在游戏连接或重连过程中调用。
| 错误 | 触发时机 | 处理方式 |
|---|---|---|
ProviderAlreadyLinked | 该提供方账号属于另一个 Player,并且设置了 result.Conflict。 | 让玩家选择合并,或切换到那个 Player。 |
ProviderNotLinked | 解除关联一个该 Player 并未关联的提供方。 | — |
LastProviderUnlinkForbidden | 解除关联该 Player 的最后一个提供方。 | 先关联另一个提供方。 |
MergeProviderConflict | 两个 Player 都拥有同一提供方的账号。 | 先解除其中一个的关联,再合并。 |
DeviceBanned | 该设备已被封禁。 | 告知玩家;重新登录也没有用。 |
Forbidden | 该 Player 已被封禁或暂停:Error.BackendCode 为 player_banned 或 player_suspended。 | 告知玩家。 |
InvalidCredential · Unauthorized | 提供方的 token 被拒绝或已过期。 | 从提供方获取新的 token 后重试。 |
封禁和暂停对本次登录是最终结果
被封禁的设备或账号在运营人员于 Players 中解除之前无法登录。不要循环重试。
如果平台之后结束了会话(例如在封禁之后),会触发 PlayServAuth.SessionLost:见 Connection & Session。
通过 PlayServ Auth Token 或 PlayServ Webhook 使用你自己的认证服务器,即将推出。
后续步骤
- SSO & Auth —— 开启提供方并填写它们的凭据
- 管理 Player —— 你的玩家所获得的账号
- 连接与 Session —— 会话如何保持,以及何时结束
更新于 2026年10月19日