域(服务器)与用户管理接入指南

1. 基本概念

域 (Realm)

对应游戏中服务器的概念，每个 Passport 服务下可以有一个或多个域。 域（Realm）预置的"外部关联ID"可用于关联真实的服务器ID。

用户 (User)

对应游戏中用户账号的概念，用户首次登录时自动创建用户账号。

角色 (Persona)

对应游戏中角色的概念，用户可在同一个用户账号(User)下不同游戏服务器(Realm)中创建不同的角色(Persona)。

实名认证

支持使用用户真实姓名和身份证号码进行实名认证，返回认证结果。

2. 功能配置与管理

域（服务器）管理

启用 UOS Passport 服务后，会自动创建默认的域。在 UOS Passport 服务 「服务器」 页面，可以创建新的域或者对现有的域进行修改、删除等操作。可以调整服务器状态参数，包含"待上线"、"运行中"、"维护中"和"已离线"等，用于管理服务器状态。

用户管理

进入 UOS Passport 服务 「账号 -> 用户管理」 页面查看用户信息。

支持查看、搜索用户。点击用户ID可查看用户详情，支持为用户打标签、修改用户状态等操作，支持查看该用户下的所有角色列表。
用户列表下面的敏感词检测模块，开启该配置后，将对用户名/角色名进行敏感词检测，涉及功能包括更新用户信息中的用户名，更新角色信息中的角色名称，以及使用外部账户登录时的角色名。

角色管理

进入 UOS Passport 服务 「账号 -> 角色管理」 页面查看角色信息。
支持查看、搜索角色。点击角色ID可查看角色详情，支持为角色打标签、修改角色状态等操作，支持查看该角色在所有域（服务器）下的好友、排行榜、邮箱、成就、礼包和背包等情况。

好友配置

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

标签管理

支持创建标签、查看使用该标签的用户和角色、修改标签名和删除标签等操作。

举报管理

支持查询、查看举报详情、修改举报状态、删除举报记录、解封或封禁角色等操作。

3. 在 Unity 中接入 SDK

在接入 SDK 前，请确保在代码中引入了 Passport 的命名空间：

using Unity.Passport.Runtime;

接入用户登录模块

外部账号系统登录

参考 「外部账号系统登录」 正确接入外部ID系统。 确保在调用 用户管理 相关方法之前 已完成外部ID系统的接入

Passport登录

参考 「Passport 登录」 正确接入 Passport Login，确保在调用 用户管理 相关方法之前 用户已经登录完成。

获取域列表

var list = await PassportSDK.Identity.GetRealms();
foreach (var realm in list)
{
  Debug.Log(realm.Name);
}

创建角色

注意：一个 User 在同一个 Realm 下只能创建一个 Persona。

var realmID = "<RealmID>"; // 域 ID 可从「获取域列表」步骤中获得
var persona = await PassportSDK.Identity.CreatePersona("<YourDisplayName>", realmID);
Debug.Log(persona.PersonaID);

更新角色信息

var persona = await PassportSDK.Identity.UpdatePersona("<YourDisplayName>", "<YourIconUrl>");
Debug.Log(persona.DisplayName);

获取当前用户所有域下角色列表

var personas = await PassportSDK.Identity.GetPersonas();
foreach (var persona in personas)
{
    Debug.Log(persona.DisplayName);
}

获取当前用户在指定域下的角色

var realmID = "<RealmID>"; // 域 ID 可从「获取域列表」步骤中获得
var persona = await PassportSDK.Identity.GetPersonaByRealm(realmID);
Debug.Log(persona.DisplayName);

选择角色

await PassportSDK.Identity.SelectPersona(personaID);

实名认证

var success = await PassportSDK.Identity.VerifyRealName("<YourName>", "<YourIDCardNum>");
Debug.Log($"VerifyRealName: {success}");

删除角色

// 删除角色，这将永久删除玩家的角色及相关数据，谨慎调用。在调用此 API 之前，建议提醒并提示玩家。
await PassportSDK.Identity.DeletePersona();

举报玩家

var targetPersonaID = "<targetPersonaID>"; // 被举报玩家的角色ID
var reportType = "作弊开挂"; // 举报类型，默认为 Default,
var content = "玩家开透视外挂"; // 举报内容
var result = await PassportFeatureSDK.Report.ReportPlayer(targetPersonaID, reportType, content);
Debug.Log(result.Report.TargetDisplayName);
Debug.Log(result.Report.Content);

撤回举报

var reportID = "<reportID>"; // 举报ID
await PassportFeatureSDK.Report.RevokeReport(reportID);

获取玩家举报列表

var result = await PassportFeatureSDK.Report.SearchPlayerReports();
foreach (var report in result.Reports)
{
   Debug.Log(report.TargetDisplayName);
   Debug.Log(report.Content);
}

4. 附录

核心类和接口

域/用户管理

namespace Unity.Passport.Runtime
{
    public static class PassportSDK
    {
        public class Identity
        {
            // 获取域列表
            public static async Task<List<Realm>> GetRealms() {}

            // 在当前用户+指定域下创建角色
            public static async Task<Persona> CreatePersona(string displayName, string realmID, string iconUrl = "") {}

            // 更新角色信息
            public static async Task<Persona> UpdatePersona(string displayName, string iconUrl = "",
                  Dictionary<string, string> properties = null) {}

            // 获取当前用户在所有域下的角色列表
            public static async Task<List<Persona>> GetPersonas(string realmID = null) {}

            // 获取当前用户在指定域下的角色
            public static async Task<Persona> GetPersonaByRealm(string realmID) {}

            // 选择角色（设置当前角色）
            public static async Task<SelectPersonaResult> SelectPersona(string personaID) {}

            // 实名认证
            public static async Task<bool> VerifyRealName(string name, string idCardNum) {}

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

举报

namespace Unity.Passport.Runtime
{
    public partial class PassportFeatureSDK
    {
        public class Report
        {
            // 举报玩家
            public static async Task<ReportPlayerResponse> ReportPlayer(string targetPersonaId,
                  string reportType, string content, Dictionary<string, string> properties = null) {}

            // 撤回举报
            public static async Task<RevokeReportResponse> RevokeReport(string reportId) {}

            // 获取玩家举报列表
            public static async Task<SearchPlayerReportsResponse> SearchPlayerReports(uint start = 0, uint count = 10) {}
        }
    }
}

服务端 API

参见 「Passport 服务端API接入指南」 。

客户端 API

参见 「Passport 客户端API接入指南」 。

错误码

参见 「Passport 错误码」 。