跳到主要内容
Authentication 与 Players

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

用户登录

每个玩家都从匿名 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.PlayerIdPlayer 的 PlayServ ID,形如 plr_…。添加提供方后保持不变。
PlayServAuth.SessionKind匿名时为 Anonymous,关联提供方后为 Registered,登录前为 None。
PlayServAuth.CurrentSession.LinkedProviders已关联到该 Player 的提供方。

要给新的匿名 Player 命名(包括退出登录后新建的那个),在连接之前通过代码设置 SDK 设置中的 AnonymousDisplayName。它不会重命名已有的 Player。


通过提供方登录

从提供方拿到玩家的 token,转换成凭证(proof),再传给 LoginExternalAsync。

提供方凭证配套包
AppleFromAppleIdToken(idToken, nonce)com.playserv.apple-signin,使用 iOS 上的 Sign in with Apple
GoogleFromGoogleIdToken(idToken, nonce)com.playserv.google-signin,基于 Google Sign-In plugin for Unity
FacebookFromFacebookLimitedLoginToken(token, nonce);nonce 必填com.playserv.facebook-login,使用 Meta SDK 的 Limited Login
EpicFromEpicExternalAuthToken(token)com.playserv.epic-auth,使用 EOS plugin for Unity
SteamFromSteamTicket(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 使用你自己的认证服务器,即将推出。


后续步骤

更新于 2026年10月19日