04/29/2024 11:54:53

好友模块开发

一、插件开发说明

好友模块是 MSDK 的一个社交功能模块，主要功能包括：

（1）发送消息功能，消息类型包括好友邀请、文字、链接、图片、音乐、视频、小程序等。（2）分享功能（微信朋友圈、QQ 空间、Facebook TimeLine、Twitter），分享类型包括文字、图片、链接、音乐、视频。

其中，发送消息功能分为两类：

静默发送 (Silence)，调用 API 后直接分享，在应用后台执行并无弹窗
弹窗发送 (Dialog)，调用 API 后弹出分享框，用户需要进一步操作才能分享

具体参见 MSDK 好友模块

二、客户端插件开发

2.1 Android 平台

2.1.1 类实现规则说明

包名规则：固定为 com.tencent.gcloud.msdk.friend
类名规则：渠道 + Friend，如：GarenaFriend
必须实现 IFriend 接口
- share 函数，实现分享功能
- sendMessage 函数，实现消息发送功能
- isBackendSupported 函数，是否将数据发送到后台实现，如 QQ 渠道的分享功能可以通过服务器发送，则返回 true 让服务器处理相关逻辑
- sendToGameCenter 函数，实现发送到游戏中心功能
- addFriend 函数，实现渠道加好友功能，如玩家通过调用该接口，实现 Facebook 中好友添加
- queryFriends 函数，实现查询好友功能，一般包括：游戏内好友、社交好友两类
- needOpenid2Uid 函数，实现将 MSDKFriendReqInfo.user 中的 MSDK Openid 转换为渠道的用户 ID
必须实现一个 public CLASSNAME(String seqID) 构造函数。通常用于函数初始化

2.1.2 回调字段说明

回调函数说明，可参考客户端插件开发规则

observerID 回调函数 ID
- 一般填写（除查询好友方法外）填写渠道方法中传入的 observerID 即可
- 查询好友方法的 observerID 为 MSDKObserverID.MSDK_FRIEND_OBSERVER_QUERY_FRIEND
ret 返回结构，必须是 MSDKRet 的子类
- 一般的方法（除查询好友方法），返回结果为 MSDKRet
- 查询好友方法，返回结果为 MSDKFriendRet，将好友信息填入 MSDKFriendRet.friendInfoList 中
- MSDKPersonInfo 为好友信息结构体
  - openid，用户的 MSDK Openid，渠道一般填空
  - userName，用户昵称，可为空
  - gender，用户性别，可为空
  - pictureUrl，用户头像，可为空
  - country，用户国家，可为空
  - province，用户省份，可为空
  - city，用户城市，可为空
  - language，用户语言，可为空
methodNameID MSDK 定义的函数 ID，用于回调方法定义
- MSDKMethodNameID.MSDK_FRIEND_SHARE 为分享方法 ID
- MSDKMethodNameID.MSDK_FRIEND_SEND_MESSAGE 为发送消息方法 ID
- MSDKMethodNameID.MSDK_FRIEND_QUERY_FRIEND 为查询好友方法 ID
- MSDKMethodNameID.MSDK_FRIEND_ADD_FRIEND 为加好友方法 ID

2.1.3 IFriend 接口

share 函数

实现分享功能。分享消息到信息墙，比如微信朋友圈、QQ空间、Facebook，信息基本是所有的好友可见。

调用渠道的分享功能，返回成功或失败即可。

  @Override
  public void share(MSDKFriendReqInfo reqInfo, String seqID, int observerID) {
      // TODO 渠道分享逻辑
      ...

      // 返回分享成功
      MSDKRet result = new MSDKRet(mMethodID, MSDKErrorCode.SUCCESS);
      IT.onPluginRetCallback(observerID, result, seqID);
  }

sendMessage 函数

实现消息发送功能。发送消息到某个或某几个特定玩家，将以聊天记录的形式呈现在渠道 App 中。

调用渠道的发送消息功能，返回成功或失败即可。

  @Override
  public void sendMessage(MSDKFriendReqInfo reqInfo, String seqID, int observerID) {
      // TODO 渠道发送消息逻辑
      ...

      // 返回发送消息成功
      MSDKRet result = new MSDKRet(mMethodID, MSDKErrorCode.SUCCESS);
      IT.onPluginRetCallback(observerID, result, seqID);
  }

isBackendSupported 函数

是否将数据发送到后台实现，如 QQ 渠道的分享功能可以通过服务器发送，则返回 true 让服务器处理相关逻辑

目前 MSDK 不支持开放平台中好友功能的后台调用，如果需要该功能的支持，请联系 MSDK 处理。目前直接返回不支持即可。
```
  @Override
  public boolean isBackendSupported(int methodID, int type, String seqID) {
      // 返回false表示好友功能不支持后台调用
      return false;
  }
```

queryFriends 函数

实现查询好友功能，一般包括：游戏内好友、社交好友两类

调用渠道的获取好友功能，返回好友列表或者直接返回失败。

  @Override
  public void queryFriends(String subChannel, int page, int count, boolean isInGame, String seqID, String extra) {
      // 返回不支持
      MSDKFriendRet ret = null;
      try {
          ret = new MSDKFriendRet(new JSONObject());
          ret.retCode = MSDKErrorCode.NOT_SUPPORT;
          // MSDKFriendRet 需要插件手动填写 retMsg
          ret.retMsg = IT.getRetMsg(ret.retCode);
          ret.methodNameID = MSDK_FRIEND_QUERY_FRIEND;
      } catch (JSONException e) {
          MSDKLog.e("[ " + seqID + " ] queryFriends json exception");
      }
      IT.onPluginRetCallback(MSDKObserverID.MSDK_FRIEND_OBSERVER_QUERY_FRIEND, ret, seqID);
  }

addFriend 函数

实现渠道加好友功能，如玩家通过调用该接口，实现 Facebook 中好友添加

调用渠道的加好友功能，返回成功或失败即可。

  @Override
  public void addFriend(MSDKFriendReqInfo reqInfo, String seqID, int observerID) {
      // 返回不支持
      IT.onPluginRetCallback(observerID,
              new MSDKRet(MSDK_FRIEND_ADD_FRIEND, MSDKErrorCode.NOT_SUPPORT), seqID);
  }

needOpenid2Uid 函数

实现将 MSDKFriendReqInfo.user 中的 MSDK Openid 转换为渠道的用户 ID

目前 MSDK 不支持开发平台的 Openid 转换功能，请通过业务自身的后台接口进行自主转换，请直接返回 false 不需要
```
  @Override
  public boolean needOpenid2Uid(int methodID, MSDKFriendReqInfo reqInfo, String seqID) {
      // 返回不需要进行转换
      return false;
  }
```
[info] 详情请参考示例代码

2.2 iOS 平台

2.2.1 类实现规则说明

命名规则：固定为 MSDKFriend + 渠道，如：MSDKFriendGarena
必须实现 MSDKFriendDelegate 协议
- share 函数，实现分享功能
- sendMessage 函数，实现消息发送功能
- 【可选】addFriend 函数，实现渠道加好友功能，如玩家通过调用该接口，实现 Facebook 中好友添加
- 【可选】queryFriends 函数，实现查询好友功能，一般包括：游戏内好友、社交好友两类
- 【可选】isBackendSupported 函数，是否将数据发送到后台实现，如 QQ 渠道的分享功能可以通过服务器发送，则返回 YES 让服务器处理相关逻辑
- 【可选】needOpenid2Uid 函数，实现将 MSDKFriendReqInfo.user 中的 MSDK Openid 转换为渠道的用户 ID

2.2.2 回调字段说明

回调函数说明，可参考客户端插件开发规则

observerID 回调函数 ID，一般填写（除查询好友方法外）填写渠道方法中传入的 observerID 即可，查询好友方法的 observerID 为 kObserverIDQueryFriend
ret 返回结构
- 一般的方法（除查询好友方法），返回结果为 InnerBaseRet
- 查询好友方法，返回结果为 InnerFriendRet，将好友信息填入 InnerFriendRet.friendInfoList 中
- InnerPersonInfo 为好友信息结构体
  - openid，用户的 MSDK Openid，渠道一般填空
  - userName，用户昵称，可为空
  - gender，用户性别，可为空
  - pictureUrl，用户头像，可为空
  - country，用户国家，可为空
  - province，用户省份，可为空
  - city，用户城市，可为空
  - language，用户语言，可为空
methodNameID MSDK 定义的函数 ID，用于回调方法定义
- kMethodNameShareToWall 为分享方法 ID
- kMethodNameSendMessageToFriend 为发送消息方法 ID
- kMethodNameQueryFriend 为查询好友方法 ID
- kMethodNameAddFriend 为加好友方法 ID

2.2.3 MSDKFriendDelegate 协议

share 函数

实现分享功能。分享消息到信息墙，比如微信朋友圈、QQ空间、Facebook，信息基本是所有的好友可见。

调用渠道的分享功能，返回成功或失败即可。

  - (void)share:(const MSDKFriendReqInfo &)reqInfo params:(MSDKBaseParams &)params observerID:(unsigned int)observerID {
  // 调用渠道分享逻辑
  ...

  // 返回分享成功
  InnerBaseRet ret(MSDKError::SUCCESS);
  ret.methodNameID = params.methodID;
  MSDKInnerObserverHolder<InnerBaseRet>::CommitToTaskQueue(ret, observerID, params.seqID);
  }

sendMessage 函数

实现消息发送功能。发送消息到某个或某几个特定玩家，将以聊天记录的形式呈现在渠道 App 中。

调用渠道的发送消息功能，返回成功或失败即可。

  - (void)sendMessage:(const MSDKFriendReqInfo &)reqInfo params:(MSDKBaseParams &)params observerID:(unsigned int)observerID {
  // 调用渠道发送消息逻辑
  ...

  // 返回发送消息成功
  InnerBaseRet ret(MSDKError::SUCCESS);
  ret.methodNameID = params.methodID;
  MSDKInnerObserverHolder<InnerBaseRet>::CommitToTaskQueue(ret, observerID, params.seqID);
  }

isBackendSupported 函数

是否将数据发送到后台实现，如 QQ 渠道的分享功能可以通过服务器发送，则返回 YES 让服务器处理相关逻辑

目前 MSDK 不支持开放平台中好友功能的后台调用，如果需要该功能的支持，请联系 MSDK 处理。目前直接返回不支持即可。
```
  - (BOOL)isBackendSupported:(int)methodID type:(int)type seqId:(NSString *)seqId {
  // 返回 NO 表示好友功能不支持后台调用
  return NO;
  }
```

queryFriends 函数

实现查询好友功能，一般包括：游戏内好友、社交好友两类

调用渠道的获取好友功能，返回好友列表或者直接返回失败。

  - (void)queryFriends:(const MSDKQueryFriendsRequest &)reqInfo params:(MSDKBaseParams &)params {
  // 返回不支持
  InnerFriendRet ret(MSDKError::NOT_SUPPORT);
  ret.methodNameID = params.methodID;
  MSDKInnerObserverHolder<InnerFriendRet>::CommitToTaskQueue(ret, kObserverIDQueryFriend, params.seqID);
  }

addFriend 函数

实现渠道加好友功能，如玩家通过调用该接口，实现 Facebook 中好友添加

调用渠道的加好友功能，返回成功或失败即可。

  - (void)addFriend:(const MSDKFriendReqInfo &)reqInfo params:(MSDKBaseParams &)params observerID:(unsigned int)observerID {
  // 返回不支持
  InnerBaseRet ret(MSDKError::NOT_SUPPORT);
  ret.methodNameID = params.methodID;
  MSDKInnerObserverHolder<InnerBaseRet>::CommitToTaskQueue(ret, observerID, params.seqID);
  }

needOpenid2Uid 函数

实现将 MSDKFriendReqInfo.user 中的 MSDK Openid 转换为渠道的用户 ID

目前 MSDK 不支持开发平台的 Openid 转换功能，请通过业务自身的后台接口进行自主转换，请直接返回 false 不需要
```
  - (BOOL)needOpenid2Uid:(int)methodId reqInfo:(const MSDKFriendReqInfo &)reqInfo seqId:(NSString *)seqId{
  // 返回不需要进行转换
  return false;
  }
```
[info] 详情请参考示例代码

三、插件服务器开发

对于获取同玩好友关系，MSDK 提供两种方式：

MSDK 帮助插件服务器托管 MSDK 已经支持的标准渠道的同玩好友关系，插件服务器无需实现好友关系接口；
对于 MSDK 不支持的渠道，插件服务器需要实现获取好友关系接口以供 MSDK 调用。

现将两种方式详细描述如下：

3.1 MSDK 托管同玩好友关系

实现 MSDK 托管同玩好友关系需要在登录时，客户端插件必须传递需要托管的渠道的渠道信息。

以 Garena 渠道为例，如果想要实现 MSDK 托管 Garena 下 Facebook 子渠道的好友关系，在登录时，channel_info中除了传递 Garena 的渠道信息之外，还要按照规范传递 Facebook 的渠道信息。

{
    "channel_info": {
        "token": "garena token",
        "sub_channelid": 4,
        "sub_channel_info": {
            "access_token": "facebook token"
        }
    },
    "device_info": {
        "uuid": "E70F7623-BAA0-4820-996F-78EE841EEBA0",
        "device_language": "zh_CN",
        "app_version": "2.0",
        "screen_dpi": 2.0,
        "resolution": "750*1334",
        "screen_dir": 1,
        "trade_mark": "APPLE",
        "manufacturer": "APPLE",
        "model": "iPhone6",
        "apn": "\u4e2d\u56fd\u79fb\u52a8;4G",
        "ramminfo": "989",
        "rom_info": "14",
        "cpu_info": "16777228-1"
    },
    "channel_dis": "App Store"
}

即 channel_info 中需要包含主渠道鉴权所需的渠道信息，子渠道鉴权所需的渠道信息以及子渠道的标识。channel_info 规范归纳如下：

"channel_info": {
    "token": "garena token",  // 主渠道鉴权所需信息，不同渠道包含不同的字段
    "sub_channelid": 4,  // 需要托管的渠道在 MSDK 中的渠道 ID，详细映射关系请见下表
    "sub_channel_info": {  // 需要托管的渠道鉴权所需信息，不同渠道包含不同的字段，详细格式请见下表
        "access_token": "facebook token"
    }
}

目前，MSDK 可以托管好友关系的渠道列表如下：

渠道名称	渠道ID（sub_channelid）	渠道鉴权所需信息（sub_channel_info）
Facebook	4	access_token

3.2 插件服务器实现获取好友接口

如果渠道支持好友列表功能，MSDK 可以调用插件服务器实现的好友接口为游戏提供好友列表功能

插件服务器需要按照如下规范实现获取好友接口：

3.2.1 接口名

接口名（/friend/friend_list/ 可以在管理端配置）

3.2.2 请求参数

参数	类型	描述	可选与否
appid	string	应用 ID	必填
uid	string	第三方渠道的用户标识	必填
token	string	第三方渠道的 token	必填
page	uint	页码	必填
page_size	uint	每页包含多少数目	必填
extraJson	json	额外信息	选填

3.2.3 返回参数

参数	类型	描述	可选与否
ret	uint	返回码， 0 表示成功，其它表示失败	必填
msg	string	返回结果详细说明	必填
count	uint	总数	必填
page	uint	页码	必填
page_size	uint	每页包含多少数目	必填
list	array	好友列表	必填
extraJson	json	自定义的额外信息	选填

list 中的对象说明：

参数	类型	描述	可选与否
uid	string	第三方渠道的用户标识	必填
gender	uint	性别，0: 未定义， 1: 男， 2:女	选填
user_name	string	用户昵称	必填
picture_url	string	头像地址	必填
extraJson	json	针对每个好友的自定义额外信息	选填

3.2.4 请求示例

请求

 POST /friend/friend_list/?channelid=101&gameid=10&os=1&sig=5c196339b9dee75c2fa52aeb2cfbb038 HTTP/1.1
 Host: openplatformtest.com
 Content-Type: application/json
 Content-Length: 169

 {
     "appid": "xxxxx",
     "uid": "openplatformtestloginuid",
     "token": "openplatformtestlogintokentest",
     "extraJson": {
         "example": "example"
     },
     "page": 1,
     "page_size": 100
 }

响应

 {
     "ret": 0,
     "msg": "success",
     "count": 1000,
     "page": 1,
     "page_size": 200,
     "list": [
         {
             "uid": "openplatformtestloginuid",
             "gender": 1,
             "user_name": "tamywang",
             "picture_url": "http://exmaple.com/example.jpg",
             "extraJson": {
                 "example": "login extra info"
             }
         }
     ]
 }

好友模块