好友列表

在多人游戏中，游戏内的玩家互动对于提升整体游戏体验和发展游戏社区至关重要。Player Network 提供了一个访问玩家游戏中好友列表的界面，其中提供了好友的 OpenID 和个人资料信息。

通过好友列表，玩家可以相互发送或接收游戏中的物品，相互聊天，组建公会或小队共同完成任务，并以游戏中能想到的多种方式相互交流。

除了游戏中的好友，Player Network 还可以检索与玩家当前登录渠道相关联的好友列表。

注册好友列表回调

开发人员可以注册以下回调函数，以接收有关好友列表事件的通知。这样，开发人员就能检测和处理查询好友列表的请求。

Unity
Unreal Engine

API	描述
AddFriendResultObserver	添加 FriendResult 回调以管理 QueryFriends 的回调
RemoveFriendResultObserver	删除 FriendResult 回调

API	描述
SetFriendResultObserver	设置好友列表的 FriendResult 回调
GetFriendResultObserver	获取好友列表的 FriendResult 回调
OnFriendResult_Implementation	实现 QueryFriends 的 FriendResult 回调

注册回调后，请按照以下说明查询各登录渠道的好友列表。

查询 Discord 好友列表

Player Network 的好友列表功能需要游戏具备访问 Discord 的 identify、relationships.read、和 activities.write 权限。更多信息，请参见 OAuth2 Scopes。

要查询 Discord 好友列表，玩家必须在设备上安装 Discord 应用程序，并使用 Discord 渠道登录游戏。调用 QueryFriends 接口，入参为当前登录渠道，用于检索好友的页码的 int，用于设置每页的好友数的 int，用于确定是否只检索同玩好友的 bool，及一个可以用于任何额外数据的可选参数。

Unity
Unreal Engine

INTLAPI.QueryFriends(1, 10, false, INTLChannel.Discord); //Organizes platform friends to 10 per page, returns to page 1 

UINTLSDKAPI::QueryFriends(EINTLLoginChannel::kChannelDiscord, 1, 10, false, "{}"); //Organizes platform friends to 10 per page, returns to page 1

查询 Epic 好友列表

Epic 好友列表支持查询平台好友和好友分页。Epic 只支持获取非同玩好友。

调用 QueryFriends 接口，入参为当前登录渠道，用于检索好友的页码的 int，用于设置每页的好友数的 int，用于确定是检索平台好友的 false，及一个可以用于任何额外数据的可选参数。

Unity
Unreal Engine

INTLAPI.QueryFriends(1, 10, false, INTLChannel.Epic); //Organizes platform friends to 10 per page, returns to page 1 

UINTLSDKAPI::QueryFriends(EINTLLoginChannel::kChannelEpic, 1, 10, false, "{}"); //Organizes platform friends to 10 per page, returns to page 1

查询 Facebook 好友列表

需要游戏项目组，自行到 Facebook 开发者管理端申请好友列表 user_friends 权限，只有在审核通过后才能使用好友列表功能。更多详情，请联系 Player Network 助手。

图片：应用审核

通过审核后，通过后台接口 /v2/friend/friend_list 获取 Facebook 好友列表。

查询 Kakao 好友列表

Kakao 好友列表只支持获取同玩好友列表。

调用 QueryFriends 接口，入参为当前登录渠道，用于检索好友的页码的 int，用于设置每页的好友数的 int，用于确定只检索同玩好友的 true，及一个可以用于任何额外数据的可选参数。

Unity
Unreal Engine

INTLAPI.QueryFriends(1, 10, true, INTLChannel.KaKao);

UINTLSDKAPI::QueryFriends(EINTLLoginChannel::kChannelKaKao);

Kakao 错误码

下表列出了一些 Kakao 渠道中的常见错误码。

错误码列表	错误信息	说明
200	成功	成功
400	BadRequest	错误的请求。一个无效的请求被发送到了服务器。未解析的数据。缺少必要的参数或参数类型错误。
401	AuthFailure	认证失败。在自动或手动登录期间交付的 IDP 的访问令牌无效。
403	Forbidden	禁用的请求。该请求是由一个未经授权的用户发送的。
404	NotFound	不支持的功能。一个不存在的服务器 API 被调用。
406	NotExistData	所请求的数据不存在或请求超出了授权范围。(例如) 注册一个不存在的优惠券等行为。例如：请求转换账号的账号已经在游戏中注册。
406	AlreadyUsedIdpAccount	尝试使用其他人已经验证过的账号进行账号转换。
409	ConflictData	数据重叠。试图再次注册不能被覆盖的数据。
461	Punishment	用户惩罚
473	ServiceUnavailable	服务不可用 (维护)。平台服务不可用。例如，平台服务器维护，等。
483	NotAllowed	不允许该操作
500	InternalError	服务器系统内部错误
1001	NetworkFailure	网络错误。设备没有连接到一个网络 (3G/LTE/WiFi)
2001	ServerTimeout	服务器超时。在一定时间内 (目前是 10秒) 没有得到服务器的响应。
2002	ServerException	服务器操作中出现异常。在处理服务器响应时发生了一个异常。
2003	InvalidResponse	来自服务器的无效响应。服务器发送了一个无效的响应。
3000	InitializationFailed	初始化失败。平台初始化失败。这意味着平台环境设置有问题，可以从错误信息描述中检查出问题。
3001	NotInitialized	未初始化。当平台未被初始化时，会调用初始化/开始以外的 API。
3002	NotAuthorized	未授权。在没有认证的情况下调用生命周期/认证 API 以外的 API。
4000	InvalidParameter	参数错误。当 API 被调用时传递的参数有错误。
4001	ClientException	客户端动作出错。客户端 SDK 动作中发生了错误。
4002	InvalidState	请求不能被处理。例如，当请求转换账号时，当前的认证没有设置为设备认证；或者虽然用户不是 KakaoStory 的用户，但用户调用 KakaoStory API。
4003	InProgress	请求正在进行中。在启动 API 的过程中，启动API被调用。登录 API 被调用，同时登录 API 正在进行中。
4010	IdpAuthFailure	KakaoTalk 登录失败
5001	NotSupported	暂不支持
6001	APINotExists	请求的 API 不存在。
7001	ExceedMonthlyUsage	已达到月度使用限额。
7002	ExceedDailyUsage	已达到每日使用限额。
7003	ExceedMaxUploadSize	已达到最大上传尺寸。
7004	ExceedMaxUploadNumber	已达到最大上传数量。
7101	MessageSettingDisabled	收件人的消息设置被禁用。
7201	KakaoTalkNotInstalled	未安装 KakaoTalk。
7202	NotKakaoTalkUser	不是 KakaoTalk 用户。
9001	UserCanceled	用户取消。用户取消发生在需要用户交互的操作中，例如 IDP 身份验证和优惠券注册。
9999	Unknown	未知错误。意外地发生了一个错误。

更多信息，请参见 Kakao 错误码。

查询 Steam 好友列表

Steam 好友列表支持查询平台好友和同玩好友，好友分页，以及查询好友状态。Steam 的同玩好友指的是最近一起进行游戏的好友，不一定在 Steam 平台添加了好友。

要使好友列表功能正常运行，玩家必须在其电脑上安装并运行 Steam，且登录状态有效。调用 QueryFriends 接口，入参为当前登录渠道，用于检索好友的页码的 int，用于设置每页的好友数的 int，用于确定是检索同玩好友还是平台好友的 bool，及一个可以用于任何额外数据的可选参数。

Unity
Unreal Engine

// 获取最近一起游戏的好友，按每页 10 个好友获取，获取第一页
INTLAPI.QueryFriends(1, 10, true, INTLChannel.Steam); 
// 获取Steam好友，按每页 10 个好友获取，获取第一页
INTLAPI.QueryFriends(1, 10, false, INTLChannel.Steam);

// 获取最近一起游戏的好友，按每页 10 个好友获取，获取第一页
UINTLSDKAPI::QueryFriends(EINTLLoginChannel::kChannelSteam, 1, 10, true, "{}");
// 获取Steam好友，按每页 10 个好友获取，获取第一页
UINTLSDKAPI::QueryFriends(EINTLLoginChannel::kChannelSteam, 1, 10, false, "{}");

Steam 好友状态

好友状态信息在 FriendResult 的 extra_json 字段中返回。

"extra_json": {
    "persona_state": 0
}

persona_state 字段说明：

值	说明
0	未登录
1	已登录
2	已登录，但繁忙
3	自动离开
4	自动离开很久
5	在线，交易中
6	在线，想玩游戏
7	在线，但对好友显示为离线。这种状态永远不会向用户公布

Steam 错误码

下表列出了一些 Steam 渠道中的常见错误码。

错误码	说明
1031	Steam Dll 加载失败
1032	需要从 Steam 平台拉取游戏
1033	Steam 初始化失败，一般是因为 `steam_appid.txt` 没有放在可执行 .exe 文件的同级目录，或者没有启动 Steam 软件造成的

查询 Switch 好友列表

Switch 好友列表支持查询平台好友和同玩好友，以及好友分页。

调用 QueryFriends 接口并传递以下入参：

当前登录渠道，也就是 Switch
代表好友页书的整数，默认从 0 开始
代表一页好友数的整数，此整数不能大于300，即一个页面最多只能有300条数据记录，且每个页面的记录数必须相同
代表支持同玩好友和渠道好友的 bool，true 表示同玩好友，false 表示渠道好友
代表任意额外信息的可选参数

Unity
Unreal Engine

INTLAPI.QueryFriends(1, 10, true, INTLChannel.Switch);

UINTLSDKAPI::QueryFriends(EINTLLoginChannel::kChannelSwitch, 1 , 10, true);

返回的数据结构为：

{
    "ret": 0,
    "msg": "",
    "method_id": 203,
    "ret_code": 0,
    "ret_msg": "Success",
    "extra_json": "{}",
    "extinfo": "{}",
    "lists": [{
        "openid": "eb4621e26d73bdab",
        "user_name": "xuzhang",
        "gender": 0,
        "picture_url": "",
        "country": "",
        "province": "",
        "city": "",
        "language": "",
        "extra_json": "{\"status\":\"0\",\"isFavorite\":\"true\",\"lastPlayedAppId\":\"0\",\"lastPlayedGroupId\":\"0\",\"lastUpdateTime\":\"1668740158\",\"isSameApplication\ ":\"false\"}"
    }, {
        "openid": "8867f26c1681ea8b",
        "user_name": "swtchtest",
        "gender": 0,
        "picture_url": "",
        "country": "",
        "province": "",
        "city": "",
        "language": "",
        "extra_json": "{\"status\":\"0\",\"isFavorite\":\"true\",\"lastPlayedAppId\":\"300761088\",\"lastPlayedGroupId\":\"300761088\",\"lastUpdateTime\":\"1670204409\",\"isSameApplication\":\"true\"}"
    }]
}

查询 VK 好友列表

VK 好友列表支持查询平台好友和好友分页。调用 QueryFriends 接口，入参为当前登录渠道，用于检索好友的页码的 int，用于设置每页的好友数的 int，用于确定是否只检索同玩好友的 bool，及一个可以用于任何额外数据的可选参数。

Unity
Unreal Engine

INTLAPI.QueryFriends(1, 10, true, INTLChannel.VK); //Organizes platform friends to 10 per page, returns to page 1 
INTLAPI.QueryFriends(1, 10, false, INTLChannel.VK); //Organizes platform friends to 10 per page, returns to page 1

UINTLSDKAPI::QueryFriends(EINTLLoginChannel::kChannelVK, 1, 10, true, "{}"); //Organizes platform friends to 10 per page, returns to page 1
UINTLSDKAPI::QueryFriends(EINTLLoginChannel::kChannelVK, 1, 10, false, "{}"); //Organizes platform friends to 10 per page, returns to page 1

查询 Xbox Series X|S 好友列表

Xbox Series X|S 好友列表只支持获取同玩好友列表。

Unity
Unreal Engine

UINTLSDKAPI::QueryFriends(EINTLLoginChannel::kChannelXbox);

返回的数据结构为：

{
    "ret": 0,
    "msg": "",
    "method_id": 203,
    "ret_code": 0,
    "ret_msg": "Success",
    "extra_json": "{}",
    "extinfo": "{}",
    "lists": [{
        "openid": "10027382",
        "user_name": "xuzhang",
        "gender": 0,
        "picture_url": "",
        "country": "",
        "province": "",
        "city": "",
        "language": "",
        "extra_json": "{\"status\":\"Online\"}"
    }, {
        "openid": "10027312",
        "user_name": "swtchtest",
        "gender": 0,
        "picture_url": "",
        "country": "",
        "province": "",
        "city": "",
        "language": "",
        "extra_json": "{\"status\":\"Offline\"}"
    }]
}

注册好友列表回调​

查询 Discord 好友列表​

查询 Epic 好友列表​

查询 Facebook 好友列表​

查询 Kakao 好友列表​

查询 Steam 好友列表​

查询 Switch 好友列表​

查询 VK 好友列表​

查询 Xbox Series X|S 好友列表​