公会接入指南

1. 功能配置与管理

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

基础配置说明：

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

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

权限配置说明：

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

在 UOS Passport 服务 「公会 -> 公会管理」 中查看已创建的公会列表：

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

2. 在 Unity 中接入 SDK

在接入 SDK 前请确保完成 「功能配置」，配置公会基本信息，同时通过客户端API创建公会（参见 「Passport 客户端API接入指南」 ）。
在接入 SDK 前，请确保在代码中引入了 Passport 的命名空间：

using Unity.Passport.Runtime;

接入用户登录模块

外部账号系统登录

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

Passport登录

• 参考 「Passport 登录」 正确接入 Passport Login，确保在调用 公会 相关方法之前 用户已经登录完成。
• 安装并初始化 Feature SDK
  • 在 UOS Launcher 服务列表中，找到 Passport Feature， 点击 「Install SDK」，将服务 SDK 安装到当前项目中
    
  • 初始化 Feature SDK

    try
    {
    await PassportFeatureSDK.Initialize();
    }
    catch (PassportException e)
    {
    Debug.Log($"failed to initialize sdk: {e.Message}");
    throw;
    }

假设创建的公会ID为100001:

var guildId = "100001"; // 可替换成自己创建的公会ID

1. 随机获取公会列表

Guild.ListRandomGuildsResponse guildList = await PassportFeatureSDK.Guild.ListRandomGuilds();

// 将搜索到的公会名称打印出来
foreach (var guild in guildList.Guilds)
{
    Debug.Log(guild.GuildName);
}

public class ListRandomGuildsResponse
{
    // 结果获取的数量
    public uint Count;
    // 查询结果
    public List<GuildInfoWithCount> Guilds;
}

public class GuildInfoWithCount
{
    // 公会ID
    public string Id;
    // 公会所属的uos appID
    public string IdDomainID;
    // 公会名称
    public string GuildName;
    // 公会类型，可自定义
    public string GuildType;
    // 会长的personaID
    public string OwnerID;
    // 公会所属的域ID，与会长的域ID相同
    public string RealmID;
    // 公会状态，正常为active
    public string Status;
    // 公会是否可以在客户端随机获取公会列表中可见，private/public
    public string Visibility;
    // 公会公告
    public string Announcement;
    // 公会属性
    public Dictionary<string, string> Properties;
    // 公会系统属性
    public Dictionary<string, string> SystemProperties;
    // 加入公会是否需要申请待通过，如果未单独配置则为全局配置值
    public bool EnableGainApprovalBeforeJoin;
    // 自定义的命名空间
    public string Namespace;
    // 创建时间（UTC）
    public Timestamp CreatedAt;
    // 创建用户
    public string CreatedBy;
    // 最后修改时间（UTC）
    public Timestamp ModifiedAt;
    // 最后修改用户
    public string ModifiedBy;
    // 公会现有成员人数
    public uint MemberCount;
}

2. 搜索公会

// 查找名字中带"UOS"的公会
Guild.SearchGuildsResponse guildList = await PassportFeatureSDK.Guild.SearchGuilds("UOS");

// 将搜索到的公会名称打印出来
foreach (var guild in guildList.Guilds)
{
    Debug.Log(guild.GuildName);
}

public class SearchGuildsResponse
{
    // 符合搜索条件的总数
    public uint Total;
    // 结果起始位置
    public uint Start;
    // 结果获取的数量
    public uint Count;
    // 查询结果
    public List<GuildInfoWithCount> Guilds;
}

3. 申请加入公会

var requestMessage = "I want to join!";
Guild.CreateGuildReqResponse reqRes = await PassportFeatureSDK.Guild.JoinGuild(guildId, requestMessage);
public class CreateGuildReqResponse
{
    // 申请信息，如果加入公会时无需批准则不会返回申请留言
    public GuildRequest GuildRequest;
}

public class GuildRequest
{
    public uint Id;
    // 所属的uos appID
    public string IdDomainID;
    // 申请加入的公会ID
    public string GuildId;
    // 申请者的personaID
    public string PersonaId;
    // 申请状态，pending/approved/rejected，分别表示待审核/审核通过/被拒绝
    public string Status;
    // 申请留言，如果加入公会时无需批准则申请加入时不会返回申请留言
    public string Message;
    // 创建时间（UTC）
    public Timestamp CreatedAt;
    // 最后修改时间（UTC）
    public Timestamp ModifiedAt;
    // 最后修改用户
    public string ModifiedBy;
}

4. 查看当前玩家所在的公会信息

Guild.GetCurrentGuildSDKResponse guildInfo = await PassportFeatureSDK.Guild.GetCurrentGuild();

public class GetCurrentGuildSDKResponse
{
    public List<CurrentGuildInfo> Guilds;
}

public class CurrentGuildInfo
{
    // 公会ID
    public string Id;
    // 公会所属的uos appID
    public string IdDomainID;
    // 公会名称
    public string GuildName;
    // 公会类型，可自定义
    public string GuildType;
    // 会长的personaID
    public string OwnerID;
    // 公会所属的域ID，与会长的域ID相同
    public string RealmID;
    // 公会状态，正常为active
    public string Status;
    // 公会是否可以在客户端随机获取公会列表中可见，private/public
    public string Visibility;
    // 公会公告
    public string Announcement;
    // 公会属性
    public Dictionary<string, string> Properties;
    // 公会系统属性
    public Dictionary<string, string> SystemProperties;
    // 加入公会是否需要申请待通过，如果未单独配置则为全局配置值
    public bool EnableGainApprovalBeforeJoin;
    // 自定义的命名空间
    public string Namespace;
    // 创建时间（UTC）
    public Timestamp CreatedAt;
    // 创建用户
    public string CreatedBy;
    // 最后修改时间（UTC）
    public Timestamp ModifiedAt;
    // 最后修改用户
    public string ModifiedBy;
    // 公会现有成员人数
    public uint MemberCount;
    // 公会现有成员信息
    public List<Member> Members;
    // 成员在公会中的权限信息
    public GuildRole SelfRole;
}

public class Member
{
    // 成员的personaID
    public string MemberId;
    // 成员名称
    public string MemberName;
    // 成员权限的唯一标识
    public string Role;
    // 创建时间（UTC）
    public Timestamp CreatedAt;
    // 成员persona的头像地址
    public string IconUrl;
}

public class GuildRole
{
    // 权限所属的uos appID
    public string IdDomainID;
    // 同app下权限的唯一标识
    public string SlugName;
    // 权限名称
    public string DisplayName;
    // 等级，标识权限的高低，数字越大等级越高，比如在权限管理的时候，等级高的才能更改等级低的权限
    public uint Level;
    // 当前权限允许访问的api权限
    public Dictionary<string, bool> Permissions;
    // 权限的人数限制，比如一个公会中最多有两个副会长，limitCount为0表示没有人数限制
    public uint LimitCount;
    // 自定义的权限属性，可供记录一些游戏逻辑相关的权限
    public Dictionary<string, string> Properties;
    // 创建时间（UTC）
    public Timestamp CreatedAt;
    // 创建用户
    public string CreatedBy;
    // 最后修改时间（UTC）
    public Timestamp ModifiedAt;
    // 最后修改用户
    public string ModifiedBy;
}

5. 主动退出公会

await PassportFeatureSDK.Guild.LeaveGuild(guildId)

6. 更新公会信息

// 更新公会的名称、公告和属性
var newGuildName = "UOSGuild";
var announcement = "Welcome to UOS Guild!";
var properties = new Dictionary<string, string>
{
    { "color", "red" },
    { "region", "Asia" }
};
Guild.UpdateGuildResponse guildRes = await PassportFeatureSDK.Guild.UpdateGuild(guildId, newGuildName, announcement, properties);

public class UpdateGuildResponse
{
    public GuildInfo Guild;
}

public class GuildInfo
{
    // 公会ID
    public string Id;
    // 公会所属的uos appID
    public string IdDomainID;
    // 公会名称
    public string GuildName;
    // 公会类型，可自定义
    public string GuildType;
    // 会长的personaID
    public string OwnerID;
    // 公会所属的域ID，与会长的域ID相同
    public string RealmID;
    // 公会状态，正常为active
    public string Status;
    // 公会是否可以在客户端随机获取公会列表中可见，private/public
    public string Visibility;
    // 公会公告
    public string Announcement;
    // 公会属性
    public Dictionary<string, string> Properties;
    // 公会系统属性
    public Dictionary<string, string> SystemProperties;
    // 加入公会是否需要申请待通过，如果未单独配置则为全局配置值
    public bool EnableGainApprovalBeforeJoin;
    // 自定义的命名空间
    public string Namespace;
    // 创建时间（UTC）
    public Timestamp CreatedAt;
    // 创建用户
    public string CreatedBy;
    // 最后修改时间（UTC）
    public Timestamp ModifiedAt;
    // 最后修改用户
    public string ModifiedBy;
}

7. 查看加入公会的申请列表

Guild.ListGuildReqsResponse reqList = await PassportFeatureSDK.Guild.ListJoinGuildRequests(guildId);

// 将获取到的入会请求发起人ID打印出来
foreach (var request in reqList.GuildRequests)
{
    Debug.Log(request.PersonaId);
}

public class ListGuildReqsResponse
{
    // 符合搜索条件的总数
    public uint Total;
    // 结果起始位置
    public uint Start;
    // 结果获取的数量
    public uint Count;
    // 查询结果，只包含status为pending的请求
    public List<GuildRequest> GuildRequests;
}

8. 通过加入公会的申请

var requestId = "1"; // 可以替换成获取到的入会申请ID
await PassportFeatureSDK.Guild.ApproveJoinGuildRequest(guildId, requestId);

9. 拒绝加入公会的申请

var requestId = "2";
await PassportFeatureSDK.Guild.RejectJoinGuildRequest(guildId, requestId);

10. 移除公会成员

var memberId = "100020001";  // memberId即为角色的PersionaID
await PassportFeatureSDK.Guild.RemoveGuildMember(guildId, memberId);

11. 解散公会

await PassportFeatureSDK.Guild.DismissGuild(guildId);

12. 获取公会权限列表

Guild.ListGuildRolesResponse roleList = await PassportFeatureSDK.Guild.ListGuildRoles();

// 将搜索到的公会权限的唯一标识和名称打印出来
foreach (var role in roleList.GuildRoles)
{
    // 默认情况下，打印结果为: owner(会长)、manager(副会长)和member(成员)
    Debug.Log(role.SlugName + '(' + role.DisplayName + ')');
}

public class ListGuildRolesResponse
{
    // 公会权限列表
    public List<GuildRole> GuildRoles;
}

13. 管理公会成员的权限

// 会长可以将“manager（副会长）”赋给 memberId 为 100020001 的成员
var memberId = "100020001";
var role = "manager";
await PassportFeatureSDK.Guild.ManageMemberRole(guildId, memberId, role);

14. 会长指定任意公会成员为会长

// 会长可以指定 memberId 为 100020003 的成员为新会长
var memberId = "100020003";
await PassportFeatureSDK.Guild.AssignOwner(guildId, memberId);

15. 获取本app下的公会配置

Guild.GetGuildConfigResponse guildConfigInfo = await PassportFeatureSDK.Guild.GetGuildConfig();

public class GetGuildConfigResponse
{
    // 公会配置
    public GuildConfig GuildConfig;
}

public class GuildConfig
{
    // 配置所属的uos appID
    public string IdDomainID;
    // 公会人数限制
    public uint MemberLimitCount;
    // 加入公会的冷却时间
    public uint RestrictedMinutesAfterLeaveGuild;
    // 加入公会是否需要申请待通过，各公会也可以自己配置，公会未单独配置时则使用此项全局配置
    public bool EnableGainApprovalBeforeJoin;
    // 是否不允许公会名称唯一存在（允许重名）
    public bool DisableUniqueGuildName;
    // 创建时间（UTC）
    public Timestamp CreatedAt;
    // 创建用户
    public string CreatedBy;
    // 最后修改时间（UTC）
    public Timestamp ModifiedAt;
    // 最后修改用户
    public string ModifiedBy;
}

16. 创建公会

Guild.GuildInfo createdGuildInfo = await PassportFeatureSDK.Guild.CreateGuild("guildName", GuildVisibility.Private, "announcement", new Dictionary<string, string>
{
    {"key1", "value1"}
}, "type", false, "namespace1");

public class GuildInfo
{
    // 公会ID
    public string Id;
    // 公会所属的uos appID
    public string IdDomainID;
    // 公会名称
    public string GuildName;
    // 公会类型，可自定义
    public string GuildType;
    // 会长的personaID
    public string OwnerID;
    // 公会所属的域ID，与会长的域ID相同
    public string RealmID;
    // 公会状态，正常为active
    public string Status;
    // 公会是否可以在客户端随机获取公会列表中可见，private/public
    public string Visibility;
    // 公会公告
    public string Announcement;
    // 公会属性
    public Dictionary<string, string> Properties;
    // 公会系统属性
    public Dictionary<string, string> SystemProperties;
    // 加入公会是否需要申请待通过，如果未单独配置则为全局配置值
    public bool EnableGainApprovalBeforeJoin;
    // 自定义的命名空间
    public string Namespace;
    // 创建时间（UTC）
    public Timestamp CreatedAt;
    // 创建用户
    public string CreatedBy;
    // 最后修改时间（UTC）
    public Timestamp ModifiedAt;
    // 最后修改用户
    public string ModifiedBy;
}

3. 附录

核心类和接口

namespace Unity.Passport.Runtime
{
    public partial class PassportFeatureSDK
    {
        public class Guild
        {
            // 随机获取公会列表，常用于用户随机挑选需要加入的公会
            // 调用不受权限限制
            // count: 查询获取的数量，默认为10，最大为50
            // guildNamespace: 公会的命名空间
            public static async Task<ListRandomGuildsResponse> ListRandomGuilds(int count = 10, string guildNamespace = null){}

            // 搜索公会
            // 调用不受权限限制
            // guildName: 需要搜索的公会名称，支持模糊查询
            // start: 查询起始位置 (按照创建时间降序排序, 最后创建的在前)，默认为0
            // count: 查询获取的数量，默认为10，最大为50
            // guildNamespace: 公会的命名空间
            public static async Task<SearchGuildsResponse> SearchGuilds(string guildName, int start = 0, int count = 10, string guildNamespace = null){}

            // 申请加入公会
            // 当公会满员时，仅开启了“加入公会前验证”的情况下可以继续提交申请
            // guildId: 公会唯一标识ID
            // requestMessage: 申请留言
            public static async Task<CreateGuildReqResponse> JoinGuild(string guildId, string requestMessage){}

            // 查看当前玩家所在的公会信息
            // 没有加入公会时返回空：{"guild":null}
            public static async Task<GetCurrentGuildSDKResponse> GetCurrentGuild(){}

            // 主动退出公会
            // guildId: 公会唯一标识ID
            public static async Task<Empty> LeaveGuild(string guildId){}

            // 更新公会信息
            // 仅限拥有“更新公会信息”权限的成员可以调用
            // guildName: 公会名称
            // announcement: 公会公告
            // properties: 公会自定义属性，大小默认限制为0.5KB
            // enableGainApprovalBeforeJoin: 加入公会是否需要等待获得批准，不传则默认与全局公会配置中的此项内容一致</param>
            // visibility: 公会是否可以在客户端随机获取公会列表中可见，仅owner可以更新此项</param>
            public static async Task<UpdateGuildResponse> UpdateGuild(string guildId, string guildName, string announcement,
                Dictionary<string, string> properties, bool? enableGainApprovalBeforeJoin = null, GuildVisibility? visibility = null){}

            // 查看加入公会的申请列表
            // 仅限拥有“处理入会请求”权限的成员可以调用
            // guildId: 公会唯一标识ID
            // start: 查询起始位置 (按照创建时间降序排序, 最后创建的在前)，默认为0
            // count: 查询获取的数量，默认为10，最大为50
            public static async Task<ListGuildReqsResponse> ListJoinGuildRequests(string guildId, int start = 0, int count = 10){}

            // 通过加入公会的申请
            // 仅限拥有“处理入会请求”权限的成员可以调用
            // guildId: 公会唯一标识ID
            // requestId: 入会请求ID
            public static async Task<Empty> ApproveJoinGuildRequest(string guildId, string requestId){}

            // 拒绝加入公会的申请
            // 仅限拥有“处理入会请求”权限的成员可以调用
            // guildId: 公会唯一标识ID
            // requestId: 入会请求ID
            public static async Task<Empty> RejectJoinGuildRequest(string guildId, string requestId){}

            // 移除公会成员
            // 仅限拥有“移除公会成员”权限的成员可以调用
            // guildId: 公会唯一标识ID
            // memberId: 需要移除的成员personaID
            public static async Task<Empty> RemoveGuildMember(string guildId, string memberId){}

            // 解散公会
            // 仅限公会owner（会长）可以调用
            // guildId: 公会唯一标识ID
            public static async Task<Empty> DismissGuild(string guildId){}

            // 获取公会权限列表
            // 返回的列表中权限等级由高到低排序
            public static async Task<ListGuildRolesResponse> ListGuildRoles(){}

            // 管理公会成员的权限
            // 仅限拥有“管理公会权限”权限的成员可以调用
            // guildId: 公会唯一标识ID
            // memberId: 需要更改权限的成员personaID
            // role: 更改后的公会成员权限唯一标识(SlugName)，如"manager"
            public static async Task<Empty> ManageMemberRole(string guildId, string memberId, string role){}

            // 会长指定任意公会成员为会长
            // 仅限公会owner（会长）可以调用
            // guildId: 公会唯一标识ID
            // memberId: 需要指定为会长的成员personaID
            public static async Task<AssignOwnerResponse> AssignOwner(string guildId, string memberId){}

            // 获取本app下的公会配置
            // 调用不受权限限制
            public static async Task<GetGuildConfigResponse> GetGuildConfig(){}

            // 玩家创建公会
            // guildName: 公会名称
            // visibility: 公会是否可以在客户端随机获取公会列表中可见，默认public
            // announcement: 公会公告，限制100字以内
            // properties: 公会属性，大小默认限制为0.5KB
            // guildType: 自定义的公会类型
            // enableGainApprovalBeforeJoin: 加入公会是否需要等待获得批准，默认与全局公会配置中的此项内容一致
            // guildNamespace: 自定义的命名空间，默认为default
            public static async Task<GuildInfo> CreateGuild(string guildName, GuildVisibility? visibility = null, string announcement = null, Dictionary<string, string> properties = null, string guildType = null, bool? enableGainApprovalBeforeJoin = null, string guildNamespace = ""){}
        }
    }
}

服务端 API

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

客户端 API

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

错误码

参见 「Passport 错误码」 。