Passport 示例教程

我们为 UOS Passport 准备了示例项目，演示了登录（包括登录方式、用户协议、实名认证等）、排行榜、好友、公会、礼包和防沉迷等功能的接入方式。本教程说明了示例项目的搭建流程。

1. 创建 UOS APP

创建 UOS APP 并开启 Passport 服务的免费试用。开启服务后，将默认跳转到 Passport 配置界面。在设置中找到 App 信息，包括 App ID, App Secret 和 App Service Secret 以备在搭建 Unity 项目的过程中使用。

2. 搭建 Unity 项目

使用 不低于 2021.3(LTS) 版本的 Unity 编辑器新建 Unity 项目。

点击编辑器中 「Window -> TextMeshPro -> Import TMP Essential Resources」，将 TextMeshPro 资源导入。

安装配置 UOS Launcher

使用 UOS Launcher 安装 SDK

参考 Launcher 教程，安装 Launcher 后，关联上一步骤中创建的 UOS APP，然后安装 Passport Login SDK 和 Passport Feature SDK。

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

导入 UI 资源

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

导入示例资源

请确保 Passport Login SDK 与 Passport Feature SDK 均已成功安装，且 Passport UI 已正常引入（即存在 Assets/PassportUI 文件夹），再导入 Passport 示例资源。

点击按钮，下载 Passport 示例资源。将资源导入到 Unity 项目中。

导入后，打开 Assets/UOSPassportSample/Scenes/DemoScene.unity 场景文件，点击运行。

到这里，我们就已经完成了示例项目的搭建。

*示例代码路径

示例项目关于登录、好友、排行榜、公会、礼包和防沉迷等功能的主要代码路径如下：

Assets/
└── UOSPassportSample/
    └── Scripts/
        ├── DemoUIController.cs  # 登录示例代码
        ├── Friends/
        │   └── FriendsUIController.cs  # 好友示例代码
        ├── Leaderboard/
        │   └── LeaderboardUIController.cs  # 排行榜示例代码
        ├── Guild/
        │   └── GuildUIController.cs  # 公会示例代码
        ├── Token/
        │   └── TokenUIController.cs  # 礼包示例代码
        └── AntiAddiction/
            └── AntiAddictionUIController.cs  # 防沉迷示例代码

3. 配置功能模块

在这一版块，您可以尝试在 UOS 后台修改各功能模块的配置，看它们如何影响示例项目运行时的表现，从而进一步了解各个功能的工作原理。支持配置登录信息，包括基本信息、登录方式、实名认证与用户协议等。如需使用更多功能，请查看本教程相应部分：配置好友、配置排行榜、配置公会、配置礼包和配置防沉迷。具体流程如下：

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

基本信息

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

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

用户协议

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

参考微信登录、微信扫码登录、 QQ登录、 QQ扫码登录、苹果登录。

配置好友（可选）

在 UOS Passport 服务「账号 -> 好友配置」配置好友上限值和好友请求上限值。

排行榜配置（可选）

在 UOS Passport 服务 「排行榜」 处点击 「立即创建」，创建任意名称和唯一标识的排行榜：

点击排行榜名称进入详情页，在此处你可以看到排行榜的基本信息，以及可以自行配置的“重置管理”、“分级管理”和“奖励”三个功能模块：

重置管理：用于控制排行榜的重置，重置后该榜单的所有数据清零，可以用于新开赛季等。分为“下次重置时间”和“自动重置周期”，其中“下次重置时间”的设定决定了排行榜将在该时间进行重置，而此时若是设定了“重置周期”，其第一次执行将在“下次重置时间”后的第一个周期节点执行。
如下图所示的重置计划，排行榜将在23年9月12号的12点进行重置，同时根据重置周期计算得到首次周期重置将于23年10月1号0点执行，以此类推，往后的每月1号0点均会执行。

分级管理：用于计算每个成绩归属的等级，可用于分配段位、称号等。创建分级后，返回的成绩中可以获取到对应的等级。
如下图所示的分级，分值为70的成绩将归属于“白银”，而分值为90的成绩将归属与“黄金”。

配置公会（可选）

在 UOS Passport 服务 「公会 -> 公会配置」 配置公会的基本信息，也可以使用默认配置：

基础配置说明：

公会成员上限值: 配置公会成员上限后，公会的成员数量达到该值将不可再增加，默认50；
冷却时间(分钟): 配置冷却时间，角色在离开上一个公会后，在该冷却时间内无法加入或者创建新的公会”；
加入公会前验证: 开启加入公会验证后，新角色申请加入该公会，需要经过审核，关闭时则可以直接加入；

可在「公会配置」页面右侧「添加公会权限」，也可使用默认提供的“会长”、“副会长”和“成员”：

权限配置说明：

唯一标识(SlugName): 公会权限的唯一标识，同一个权限标识可以唯一定位一个公会权限，仅支持数字与字符组合，设置后不可更改；
名称: 公会权限的名称，可以是基于喜好、游戏世界设定等因素设置，例如默认的“会长”、“副会长”和“成员”；
人数上限: 人数上限代表该公会可以设置不超过该值的成员拥有该权限，例如名称为“副会长”的人数上限值为3，则该公会最多设置3个副会长，0则代表没有上限；
操作权限:
- 处理入会申请: 可以查看入会申请的列表，同时可以“通过 (Approve)”或者“拒绝 (Reject)”入会申请；
- 移除公会成员: 拥有该操作权限的成员可以移除等级低于自身的成员，例如拥有“移除公会成员”的“副会长”或者“会长”可以移除“成员”；
- 管理成员权限: 拥有该操作权限的成员可以修改等级低于自身的成员权限，例如拥有“管理成员权限”的“会长”可以将“成员”提成“副会长”；
- 更新公会信息: 拥有该操作权限的成员可以修改公会的名称、公告和自定义属性；
- 解散公会: 只有公会的owner（会长）可以解散公会。
自定义属性: 开发者可以在该字段设置实际开发中需要用到的信息；

点击公会名称进入详情页，在此处你可以看到公会的基本信息，也可以看到加入改公会的成员信息：

配置礼包（可选）

进入UOS Passport 「礼包 -> 活动管理」 页面进行礼包的配置与管理

配置礼包

点击左上角 「创建礼包活动」 按钮进行礼包创建。

名称
- 礼包活动的名称，不能为空，可以根据开发者需求设置
开始时间
- 默认为即刻开始。到达该时间后，礼包活动生效，可以进行兑换
结束时间
- 默认为永久有效。该时间过后，礼包活动失效，无法兑换
限定兑换使用范围（Scope）
- 礼包兑换的限定范围，默认为无限定。Scope可以是平台信息、玩家属性等
- 在玩家兑换时可以附上Scope信息，只有属于限定Scope范围才能成功兑换

礼包内容
- 礼包所包含的游戏资源，不能为空
- 名称：游戏资源的唯一识别名，可以是道具名称或者ID等
- 数量：游戏资源的数量

礼包码
- 通兑码
  - 一个礼包活动只能有一个通兑码，所有玩家都可以使用该码兑换
  - 支持手动输入和自动生成两种方式
- 唯一码
  - 每个码都是随机的、唯一的，且只能使用一次
  - 前缀：定制唯一码的固定前缀，需满足（礼包码长度 - 前缀长度 ≥ 8）
  - 限定兑换次数：每个游戏角色在该礼包活动中能够使用的唯一码数量，默认为1
- 礼包码长度范围8-20，支持英文和数字，不区分大小写

发布礼包

礼包活动在发布后才会正常生效，礼包码才能够被兑换

「活动管理」 和 「礼包详情」 页面都可以对礼包活动进行发布或下架

获取礼包码

通用码
- 在 「礼包详情」 页面中可以查看通用码的具体值
唯一码
- 可以在 「活动管理」 和 「礼包详情」 页面进行礼包码的生成操作
- 生成礼包码时，可以设定批次（便于统一管理）和数量，生成后，可以将礼包码导出至本地

配置防沉迷（可选）

使用示例项目中的 防沉迷模拟 功能，需开启模拟实名认证（仅供测试使用）。防沉迷功能是基于玩家实名认证所使用的身份证号中的生日信息来计算年龄，进而实施相应防沉迷限制。因此您可以通过使用带有不同生日信息的身份证号进行实名认证，来体验防沉迷功能。
进入 UOS Passport 「登录 -> 登录配置」 界面进行开启模拟实名功能。开启后，将不再真实校验用户输入的姓名和身份证号，仅校验格式。