外部账号系统接入

UOS Passport 为已有 ID 系统的开发者提供外部登录的方式来接入 Passport Feature 的相关服务。

Passport Feature SDK 接入

1. 安装配置 UOS Launcher

参考 Launcher 教程，安装 Launcher 后，关联 UOS APP， 开启 Passport Feature 服务并安装 Passport Feature SDK。

注意: 请务必确认在进行后续教程之前，已经成功完成了 Launcher 教程的安装步骤，否则可能导致后续接入无法顺利进行。

2. SDK 初始化

// 使用 UOS Launcher 方式初始化SDK, 更多SDK初始化方式见 sdk package sample 目录
try
{
    await PassportFeatureSDK.Initialize();
}
catch (PassportException e)
{
    Debug.Log($"failed to initialize sdk: {e.Message}");
    throw;
}

3. 使用外部 UserID 登录 (将外部系统的 UserId 关联至 UOS Passport 系统)

* 在 SDK 中使用 ExternalLogin 方法时传入的是 外部 ID系统 的 UserID/PersonalID/DisplayName.

// 外部用户登录
using Unity.UOS.Auth;
string userId = "<userId>"; // 需要登录的外部系统的用户Id
string personaId = "<personaId>"; // 可选, 需要登录的 外部系统的角色ID
string personaDisplayName = "<displayName>"; // 可选, 需要登录的角色的昵称。
string realmID = "<realmID>"; // 可选, 登录的服务器ID。
await AuthTokenManager.ExternalLogin(userId, personaId, personaDisplayName, realmID);

其中 服务器ID 可以从 「Passport -> 服务器」 中获取。RealmID 默认为可选字段， 但建议在下列用法中填入正确的 RealmID:

• 我的游戏是滚服游戏，同一个用户需要在不同的服务器中创建不同的角色
• 我的游戏可能存在删档测试等需要清空服务器角色的情况，需要删档时仅需更换一个新的 RealmID
• 我的游戏可能存在多测试服与正式服混用同一个 UOS APP 的情况，可以配合 Remote Config 在客户端获取不同的 Realm

注意: 登录过期处理

在使用外部账号登录完成后SDK默认会自行维护API所需要的 AccessToken/RefreshToken，用户可以通过 AuthTokenManager.GetAccessToken 方法获取当前 AccessToken/RefreshToken。 但是，当长时间未活跃（导致RefreshToken过期时），客户端需要自行处理SDK抛出的以下异常：

• NeedLogin: 需要重新登录以获取新的 AccessToken/RefreshToken
• Unauthenticated: Refresh Token已过期

遇到以上异常后，使用之前登录的 UserID 重新调用 ExternalLogin 接口即可。