好友接入指南

1. 基本概念

好友关系管理

• 发送好友请求：生成一个好友请求，接收方可通过接口查询并做出操作；
• 撤回好友请求：撤回指定 ID 的好友请求；
• 通过好友请求：通过指定 ID 的好友请求，请求发起方与接收方将建立好友关系；
• 拒绝好友请求：拒绝指定 ID 的好友请求；
• 获取好友列表：获取已建立好友关系的列表；
• 通过所有好友请求：通过所有收到的好友请求，并与请求发起方建立好友关系；
• 拒绝所有好友请求：拒绝所有收到的好友请求；
• 查询收到的好友请求列表：查询当前用户收到的好友请求；
• 查询发出的好友请求列表：查询当前用户发送的好友请求；
• 删除好友：单方面解除好友关系。

黑名单管理

• 添加拉黑：将提供的用户角色 ID 添加到拉黑列表，该用户将无法发送好友请求，但已有的好友关系不会解除（注意与删除好友区分，被删除的好友可以再次发送好友申请，但被拉黑的好友无法再次与拉黑方互动）；
• 取消拉黑：将提供的用户角色 ID 从拉黑列表中移除。

好友信息管理

• 设置好友备注：支持给好友设置备注；
• 设置好友状态：支持给好友设置自定义信息，如在线状态等。

角色搜索

• 搜索角色：根据角色名称搜索角色，可根据角色 ID 发送好友申请；
• 随机获取陌生角色列表：支持获取随机的默认角色列表，可根据角色 ID 发送好友申请。

2. 在 Unity 中接入 SDK

在接入 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;
    }

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

using FriendRequestStatus = Unity.Passport.Runtime.Model.FriendRequestStatus;

1. 获取好友列表

private async void GetFriendList()
{
    try
    {
        var friendList = await PassportFeatureSDK.Friends.GetFriendList();
        foreach (var friendship in friendList.Friends)
        {
            Debug.Log(friendship.DisplayName);
        }
    }
    catch (PassportException e)
    {
        Debug.Log(e.Code);
    }
}

2. 发送好友申请

public async void SendFriendRequest()
{
    try
    {
        await PassportFeatureSDK.Friends.SendFriendRequest(_currentFriend.PersonaID);
    }
    catch (PassportException e)
    {
        Debug.Log(e.ErrorMessage);
    }
}

3. 移除好友

public async void RemoveFriend()
{
    try
    {
        // 当removeBoth参数为false时，仅删除单方的好友关系，此处不传时默认为false
        // 如需删除双方的好友关系，需要传入removeBoth为true
        await PassportFeatureSDK.Friends.RemoveFriend("FriendshipID", false);
        // next step
    }
    catch (PassportException e)
    {
        Debug.Log(e.ErrorMessage);
    }
}

4. 拉黑角色

public async void BlacklistFriendForFriendList()
{
    try
    {
        await PassportFeatureSDK.Friends.BlacklistUser("currentFriendPersonaID");
    }
    catch (PassportException e)
    {
        Debug.Log(e.ErrorMessage);
    }
}

5. 搜索其他玩家

public async void Search()
{
    try
    {
        var result = await PassportFeatureSDK.Friends.SearchFriends("searchName");
        foreach (var persona in result.Personas)
        {
           Debug.Log(persona.DisplayName);
        }
    }
    catch (PassportException e)
    {
        Debug.Log(e.ErrorMessage);
    }
}

6. 获取接收到的好友请求

private async void GetFriendRequestReceivedList()
{
    try
    {
        var receivedList = await PassportFeatureSDK.Friends.GetFriendRequestReceivedList(0, 999, FriendRequestStatus.Pending);
        foreach (var request in receivedList.Requests)
        {
            Debug.Log(request.SourceDisplayName);
        }
    }
    catch (PassportException e)
    {
        Debug.Log(e.ErrorMessage);
    }
}

7. 获取发出的好友请求

private async void GetFriendRequestSentList()
{
    try
    {
        var sentList = await PassportFeatureSDK.Friends.GetFriendRequestSentList(0, 999);
        foreach (var request in sentList.Requests)
        {
           Debug.Log(request.TargetDisplayName);
        }
    }
    catch (PassportException e)
    {
        Debug.Log(e.ErrorMessage);
    }
}

8. 同意好友请求

 public async void ApproveFriendRequest()
{
    try
    {
        await PassportFeatureSDK.Friends.ApproveFriendRequest("FriendRequestId");
    }
    catch (PassportException e)
    {
        Debug.Log(e.ErrorMessage);
    }
    // next step
}

9. 拒绝好友请求

public async void RejectFriendRequest()
{
    try
    {
        await PassportFeatureSDK.Friends.RejectFriendRequest("FriendRequestId");
    }
    catch (PassportException e)
    {
        Debug.Log(e.ErrorMessage);
    }
    // next step
}

10. 撤回好友请求

public async void RevokeFriendRequest()
{
    try
    {
        await PassportFeatureSDK.Friends.RevokeFriendRequest("FriendRequestId");
        // next step
    }
    catch (PassportException e)
    {
        Debug.Log(e.ErrorMessage);
    }
}

11. 获取拉黑列表

 private async void GetBlacklistedUserList()
{
    var blockingRelationships = await PassportFeatureSDK.Friends.GetBlacklistedUserList(0, 10);

    foreach (var blockingRelationship in blockingRelationships)
    {
        Debug.Log(blockingRelationship.displayName);
    }
}

12. 从黑名单中移除

public async void UnblockUser()
{
    try
    {
        await PassportFeatureSDK.Friends.UnBlacklistUser("BlackListID");

        // next step
    }
    catch (PassportException e)
    {
        Debug.Log(e.ErrorMessage);
    }
}

13. 获取随机陌生角色列表

public async void FindFriendsRandomly()
{
    var friendList = await PassportFeatureSDK.Friends.FindFriendsRandomly("realmID", 10);
    foreach (var persona in friendList.Personas)
    {
        Debug.Log(persona.DisplayName);
    }
}

14. 查询好友在线状态

private async void GetFriendPresence()
{
    List<string> friendshipIDs = new List<string> { "friendshipID1", "friendshipID2", "friendshipID3" };
    try
    {
        var presenceDictionary = await PassportFeatureSDK.Friends.GetFriendPresenceList(friendshipIDs);

        foreach (var kvp in presenceDictionary)
        {
            // next step
        }
    }
    catch (PassportException e)
    {
        Debug.Log(e.Code);
    }
}

15. 设置玩家在线状态及其他属性

private async void SetPresence(string status)
{
    var presence = new PassportFriendPresence()
    {
        status = status,
        Properties = new Dictionary<string, string>()
    };
    try
    {
        await PassportFeatureSDK.Friends.SetPresence(presence);
    }
    catch (PassportException e)
    {
        Debug.Log(e.Code);
    }
}

16. 获取黑名单角色状态信息

public async void GetBlacklistPresence()
{
    try
    {
        var blacklistPresence = await PassportFeatureSDK.Friends.GetBlacklistPresence("blackListID");
        Debug.Log(blacklistPresence.status);
    }
    catch (PassportException e)
    {
        Debug.Log(e.ErrorMessage);
    }
}

17. 获取黑名单角色状态信息列表

public async void GetBlacklistPresenceList()
{
    try
    {
        List<string> blacklistIDs = new List<string> {"blackListID1", "blackListID2"};
        var blacklistPresenceList = await PassportFeatureSDK.Friends.GetBlacklistPresenceList(blacklistIDs);
        foreach (var blacklistPresence in blacklistPresenceList)
        {
            Debug.Log(blacklistPresence.Key);
            Debug.Log(blacklistPresence.Value.status);
        }
    }
    catch (PassportException e)
    {
        Debug.Log(e.ErrorMessage);
    }
}

3. 附录

核心类和接口

namespace Unity.Passport.Runtime
{
    public partial class PassportFeatureSDK
    {
        public class Friends
        {
            // 发送好友请求
            // targetPersonaID: 目标角色的角色 ID
            public static async Task<FriendRequest> SendFriendRequest(string targetPersonaID) {}

            // 获取好友请求信息
            // friendRequestID: 请求的 ID
            public static async Task<FriendRequest> GetFriendRequest(string friendRequestID) {}

            // 获取好友数量上限 (默认为50，上限为300)
            public static long GetMaxFriendCount() {}

            // 获取已发送且未处理的好友请求数量上限 (默认为50，上限为300)
            public static long GetMaxPendingFriendRequestCount() {}

            // 获取发出的好友请求列表
            // start: 查询起始位置 (按创建时间降序排列)，默认为0
            // count: 查询获取的数量，默认为10
            public static async Task<GetFriendRequestListResponse> GetFriendRequestSentList(int start = 0,
                int count = 10, FriendRequestStatus requestStatus = FriendRequestStatus.Pending) {}

            // 获取收到的好友请求
            // start: 查询起始位置 (按创建时间降序排列)，默认为0
            // count: 查询获取的数量，默认为10
            // requestStatus: 好友请求的状态，枚举值为 Pending 未处理的、Approved 已同意的、Rejected 已拒绝的、Expired 过期的、Revoked 撤回的。
            // 默认值为 FriendRequestStatus.Pending
            public static async Task<GetFriendRequestListResponse> GetFriendRequestReceivedList(int start = 0,
                int count = 10, FriendRequestStatus requestStatus = FriendRequestStatus.Pending) {}

            // 通过好友请求
            // friendRequestID：好友请求 ID
            public static async Task<Tuple<FriendRequest, FriendInfo>> ApproveFriendRequest(string friendRequestID) {}

            // 拒绝好友请求
            // friendRequestID：好友请求 ID
            public static async Task<FriendRequest> RejectFriendRequest(string friendRequestID) {}

            // 撤回好友请求
            // friendRequestID：好友请求 ID
            public static async Task<FriendRequest> RevokeFriendRequest(string friendRequestID) {}

            // 通过所有好友请求
            public static async Task<List<BatchProcessFriendRequestResult>> ApproveAllFriendRequest() {}

            // 拒绝所有好友请求
            public async Task<List<BatchProcessFriendRequestResult>> RejectAllFriendRequest() {}

            // 获取好友列表
            // start: 查询起始位置 (按创建时间降序排列)，默认为0
            // count: 查询获取的数量，默认为10
            public static async Task<GetFriendListResponse> GetFriendList(int start = 0, int count = 10) {}

            // 删除好友
            // friendshipID: 好友关系 ID
            // removeBoth: 是否删除双方好友关系
            public static async Task RemoveFriend(string friendshipID, bool removeBoth = false) {}

            // 更新好友信息
            // friendshipID: 好友关系 ID
            // alias: 好友备注名称
            public static async Task UpdateFriendInfo(string friendshipID, string alias = "") {}

            // 获取好友在线信息
            // friendshipID: 好友关系 ID
            public static async Task<PassportFriendPresence> GetFriendPresence(string friendshipID) {}

            // 批量获取好友在线信息
            // friendshipIDs: 好友关系 ID 列表
            public static async Task<Dictionary<string, PassportFriendPresence>> GetFriendPresenceList(
                List<string> friendshipIDs) {}

            // 设置当前角色在线信息
            // presence: 在线状态
            public static async Task SetPresence(PassportFriendPresence presence) {}

            // 搜索其他玩家
            // personaName: 角色名称，支持模糊搜索
            // realmID: 域 ID（可选参数，无则在全部服务器中搜索）
            // start: 查询起始位置，默认为 0
            // count: 查询获取的数量，默认为 10
            // personaID: 目标ID（只支持精确搜索），与角色名称二选一
            public static async Task<SearchFriendsResponse> SearchFriends(string personaName = null, string realmID = "", uint start = 0, uint count = 10, string personaID = null) {}

            // 随机搜索其他角色
            // realmID: 域 ID
            // count: 查询获取的数量，默认为 10
            public static async Task<FindFriendsRandomlyResponse> FindFriendsRandomly(string realmID,
                uint count = 10) {}

            // 添加拉黑
            // targetPersonaID: 目标角色的角色 ID
            public static async Task<PassportBlackList> BlacklistUser(string targetPersonaID) {}

            // 取消拉黑
            // blacklistID: 拉黑关系 ID
            public static async Task UnBlacklistUser(string blacklistID) {}

            // 获取拉黑列表
            // start: 查询起始位置，默认为 0
            // count: 查询获取的数量，默认为 10
            public static async Task<List<PassportBlackList>> GetBlacklistedUserList(int start = 0, int count = 10) {}

            // 获取黑名单角色状态信息
            // blacklistID: 黑名单ID
            public static async Task<PassportBlacklistPresence> GetBlacklistPresence(string blacklistID) {}

            // 批量获取黑名单角色状态信息
            // blacklistIDs: 黑名单ID列表
            public static async Task<Dictionary<string, PassportBlacklistPresence>> GetBlacklistPresenceList(List<string> blacklistIDs) {}
        }
    }
}

服务端 API

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

客户端 API

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