Passport Login 接入指南

功能配置与管理

进入 UOS Passport 「登录 -> 登录配置」界面进行登录配置。根据需要配置基本信息、登录方式、用户协议等。

基本信息

配置登录界面标题栏的基本信息，包括公司名称、公司图标(Logo)，可以根据预览情况进行调整。

在此处开启模拟短信验证和模拟实名认证。开启模拟短信验证后，将不再发送真实验证短信，并使用默认验证码「111111」。开启模拟实名认证后，将不再真实校验用户输入的姓名和身份证号，仅校验格式。

用户协议

配置登录时协议界面内容，包括协议的标题、文本以及附带协议链接，可以根据预览情况进行调整。

需要去相应登录渠道进行申请，参考微信登录、微信扫码登录、 QQ登录、 QQ扫码登录、苹果登录。申请成功后，将获取到的登录渠道信息（ID, Secret 等）填入到 Passport 登录配置中。

在 Unity 中接入 SDK

安装配置 UOS Launcher

使用 UOS Launcher 安装 SDK

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

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

导入 UI 资源

安装过程中，编辑器提示 「导入 PassportUI 资源」，点击导入。
如未导入，请手动点击编辑器菜单 「UOS -> Passport -> Import PassportUI」 导入。

创建脚本

首先，在你的项目中新建脚本 UIController.cs，将以下代码粘贴到该脚本文件中。

using System.Collections.Generic;
using System.Linq;
using Passport;
using UnityEngine;
using Unity.Passport.Runtime.UI;
using Unity.Passport.Runtime;

namespace Unity.Passport.Sample.Scripts
{
    public class UIController : MonoBehaviour
    {
        // sdk 配置（Config 是 SDK 初始化时的配置）
        private readonly PassportUIConfig _config = new()
        {
            AutoRotation = true, // 是否开启自动旋转，默认值为 false。
            InvokeLoginManually = false, // 是否通过自行调用 Login 函数启动登录面板，默认值为 false。
            Theme = PassportUITheme.Dark, // 风格主题配置。
            UnityContainerId = "unity-container" // WebGL 场景下 Unity 实例容器 Id。
        };

        // sdk 回调
        private void _callback(PassportEvent e)
        {
            // event: 不同情况下的回调事件，详情可以参考下面的回调类型。
            switch (e)
            {
                case PassportEvent.RejectedTos:
                    Debug.Log("用户拒绝了协议");
                    break;
                case PassportEvent.LoggedIn:
                    Debug.Log("完成登录");
                    break;
                case PassportEvent.Completed:
                    Debug.Log("完成所有流程");
                    SelectPersona();
                    break;
                case PassportEvent.LoggedOut:
                    Debug.Log("用户登出");
                    break;
            }

        }
        private void Start()
        {
            // 调用 SDK
            PassportUI.Init(_config, _callback);
        }

        // 登出
        public void Logout()
        {
            PassportUI.Logout();
        }

        // 选择角色
        private async void SelectPersona()
        {
            // 选择域
            var realms = await PassportSDK.Identity.GetRealms(); // 获取域列表
            var realmID = realms[0].RealmID; // 根据需要自行选择域
            // var realmID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"; // 也可以填写固定的 RealmID 而不是动态获取

            // 获取（或创建）与选择角色
            Persona persona = null;
            var personas = await PassportSDK.Identity.GetPersonas(); // 获取角色列表
            if (!personas.Any())
            {
                // 若没有角色，则新建角色
                persona = await PassportSDK.Identity.CreatePersona("YourDisplayName", realmID);
            }
            else
            {
                // 若有角色，则选择第一个角色
                persona = personas[0];
            }
            // 选择角色
            await PassportSDK.Identity.SelectPersona(persona.PersonaID);
        }
    }
}

搭建场景

在编辑器中新建场景，或使用已有的场景。
检查场景中是否存在事件系统（Event System）。若不存在，则在编辑器 Hierarchy 面板中，单击右键，选择 「UI -> Event System」，为当前场景添加事件系统。
点击编辑器中 「Window -> TextMeshPro -> Import TMP Essential Resources」，将 TextMeshPro 资源导入。
在场景中创建空游戏对象，命名为 UIController，并将上一步骤中的 UIController.cs 脚本挂载到该对象上。
点击运行。

若运行时若被其他 UI 界面遮挡，可根据游戏的 UI 情况，自行修改 prefab 的展示顺序至合适数值（双击打开PassportUI/Resources/Prefabs/LoginPanelsV2.prefab，修改 Canvas 组件的 Sort Order 属性）。

关于登出：
SDK 提供的自带UI登录界面未包含登出的集成，用户可在游戏中需要登出的地方调用SDK提供的登录接口 PassportUI.Logout() 来登出账号。

附录

界面预览

Passport Login SDK 提供了开箱即用的 UI 界面，包含用户协议、登录、实名认证和重新登录等界面，画风简洁清新，旨在适配绝大多数的游戏风格。

用户协议界面

后台支持配置是否开启用户协议，支持自定义配置用户协议标题、主文本和附加协议等。当用户协议开启时，界面将呈现如下效果：

后台支持配置登录方式，包含手机号、微信 OAuth、QQ OAuth、苹果 OAuth、微信扫码和 QQ扫码等。在开启手机号、微信 OAuth、QQ OAuth和苹果 OAuth登录时，界面将呈现如下效果：

手机号验证码输入界面预览如下：

实名认证界面

后台支持配置是否开启实名认证。开启时界面预览如下：

重新登录界面

用户退出当前账号，将进入重新登录界面。预览如下：

您也可以「在线体验」试用登录界面。

核心类和接口

namespace Unity.Passport.Runtime.UI
{
    public class PassportUI : MonoBehaviour
    {
        // SDK UI 初始化，传入配置和回调函数
        public static async Task Init(PassportUIConfig config, Action<PassportEvent> callback) {}

        // 触发登录流程（用户协议、注册与登录、实名认证）
        public static void Login() {}

        // 用户登出
        public static void Logout() {}
    }
}

namespace Unity.Passport.Runtime
{
    public static class PassportSDK
    {
        public class Identity
        {
            // 获取用户信息
            public static async Task<UserProfileInfo> GetUserProfileInfo() {}

            // 更新用户信息
            public static async Task UpdateUserProfileInfo(string displayName = "", string avatarUrl = "") {}

            // 删除用户，这将永久删除玩家的用户及相关数据，谨慎调用。在调用此 API 之前，建议提醒并提示玩家
            public static async Task DeleteUser() {}
        }
    }
}

注意: 登录过期处理

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

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

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