05/15/2024 15:19:45

Friend Module Development

I. Plugin development instructions

The Friend module is a social function module of MSDK. Its main functions include:

(1) The message sending function. Message types includes friend invitation, text, link, image, music, video, miniApp, etc.
(2) Sharing function (WeChat Moment, QZone, Facebook TimeLine, Twitter). Shared message types include text, image, link, music, and video.

The message delivery function is divided into two categories:

Send messages by the Silence mode: share messages directly after calling API. The silence delivery process is executed in the app's backend and it has no popup window
Send messages by the Dialog mode: a share box will pop up after API is called. The user needs to make further operations to share messages

For details, please see MSDK Friend Module

II. Client Plugin Development

2.1 Android Platform

2.1.1 Class implementation rules instructions

Package naming rule: fixed as com.tencent.gcloud.msdk.friend
Class naming rule: channel + Friend, such as: GarenaFriend
Must implement the 'IFriend' interface
- share function, which implements the sharing function
- sendMessage function, which implements the message sending function
- isBackendSupported function, which judges whether to send data to the backend to be implemented. For example, QQ channel's sharing function can send data through the server, then return "true" to let the server handle the relevant logic
- sendToGameCenter function, which implements the function of sending data to the Game Center
- addFriend function, which implements the function of adding friends in channels. For example, a player can add friends in Facebook by calling the interface.
- queryFriends function, which implements the function of querying friends, generally including: in-game friends, and social friends
- needOpenid2Uid function, which converts MSDK Openid inMSDKFriendReqInfo.user into the user ID of the channel
Must implement a public CLASSNAME (String seqID) constructor, which is usually used for function initialization

2.1.2 Description of callback fields

As for the description of the callback function, please refer to Client Plugin Development Rules

observerID callback function ID
- Generally filled in (except for the friend query method); just filled in wth observerID passed in by the channel method
- The 'observerID' of the friend query method is MSDKObserverID.MSDK_FRIEND_OBSERVER_QUERY_FRIEND
ret return struct must be a subclass of MSDKRet
- For common methods (except the friend query method), the return result is MSDKRet
- For the friend query method, the return result is MSDKFriendRet. Fill the friend information into MSDKFriendRet.friendInfoList
- MSDKPersonInfo is a friend information struct
  - `openid, the user's MSDK Openid; for channels, it is generally left blank
  - userName, the user's nickname, which can be empty
  - gender, the user's gender, which can be empty
  - pictureUrl, the user's avatar, which can be empty
  - country, the user's country, which can be empty
  - province, the user's province, which can be empty
  - city, the user's city, which can be empty
  - language, the user's language, which can be empty
methodNameID Function ID defined by MSDK, used to define the callback method
- MSDKMethodNameID.MSDK_FRIEND_SHARE is the sharing method's ID
- MSDKMethodNameID.MSDK_FRIEND_SEND_MESSAGE is the message sending method's ID
- MSDKMethodNameID.MSDK_FRIEND_QUERY_FRIEND is the friend query method's ID
- MSDKMethodNameID.MSDK_FRIEND_ADD_FRIEND is the friend adding method's ID

2.1.3 IFriend interface

share function

Implement the sharing function. Share messages to the information wall, such as WeChat Moment, QZone, Facebook, information is basically visible to all friends.

Call the channel's sharing function. It is only needed to return "success" or "failure".

  @Override    
  public void share(MSDKFriendReqInfo reqInfo, String seqID, int observerID) {    
      // TODO The channel's sharing logic    
      ...    

      // Return "Share the message successfully"    
      MSDKRet result = new MSDKRet(mMethodID, MSDKErrorCode.SUCCESS);    
      IT.onPluginRetCallback(observerID, result, seqID);    
  }

sendMessage function

Implement the message sending function. Send a message to one or more specific players and present it in the channel app in the form of chat record.

Call the message sending function of the channel. It is only needed to return "success" or "failure".

  @Override    
  public void sendMessage(MSDKFriendReqInfo reqInfo, String seqID, int observerID) {    
      // TODO The channel's message sending logic    
      ...    

      // Return "Send the message successfully"    
      MSDKRet result = new MSDKRet(mMethodID, MSDKErrorCode.SUCCESS);    
      IT.onPluginRetCallback(observerID, result, seqID);    
  }

isBackendSupported function

Whether to send data to the backend for implementation. For example, if the sharing function of the QQ channel can be sent by the server, the channel returns "true" to let the server handle the relevant logic.

MSDK currently does not support the backend call of the friends function in the open platform. If your game needs support for this function, please contact MSDK for processing. Direct return is currently not supported.
```
  @Override    
  public boolean isBackendSupported(int methodID, int type, String seqID) {    
      // Return "false", indicating that the friends function does not support being called by the backend    
      return false;    
  }
```

queryFriends function

Implement the function of querying friends, generally including: in-game friends, and social friends

Call the channel's friend-getting function. Return the friends list or return "failure" directly.

  @Override    
  public void queryFriends(String subChannel, int page, int count, boolean isInGame, String seqID, String extra) {    
      // Return "Not supported"    
      MSDKFriendRet ret = null;    
      try {    
          ret = new MSDKFriendRet(new JSONObject());    
          ret.retCode = MSDKErrorCode.NOT_SUPPORT;    
          // MSDKFriendRet requires the plugin to fill in retMsg manually    
          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 function

Implement the channel's friend adding function. For example, the player can add friends in Facebook by calling the interface.

Call the channel's friend adding function. It is only needed to return "success" or "failure".

  @Override    
  public void addFriend(MSDKFriendReqInfo reqInfo, String seqID, int observerID) {    
      // Return "Not supported"    
      IT.onPluginRetCallback(observerID,    
              new MSDKRet(MSDK_FRIEND_ADD_FRIEND, MSDKErrorCode.NOT_SUPPORT), seqID);    
  }

needOpenid2Uid function

Implement the conversion of MSDK Openid in 'MSDKFriendReqInfo.user' to the user ID of the channel

MSDK currently does not support the Openid conversion function of the open platform. Please use the game's own backend interface to convert Openid. Please return "false" directly if not needed.
```
  @Override    
  public boolean needOpenid2Uid(int methodID, MSDKFriendReqInfo reqInfo, String seqID) {    
      // Return "Don't need conversion"    
      return false;    
  }
```
[info] For details, please refer to Demo Code

2.2 iOS Platform

2.2.1 Class implementation rules instructions

Naming rules: Fixed as MSDKFriend + channel, such as: MSDKFriendGarena
Must implement the MSDKFriendDelegate protocol
- share function, which implements the sharing function
- sendMessage function, which implements the message sending function
- [Optional] addFriend function, which implements the channel's friend adding function. For example, the player can add friends in Facebook by calling the interface.
- [Optional] queryFriends function, Implement the function of querying friends, generally including: in-game friends, and social friends
- [Optional] isBackendSupported function, which judges whether to send data to the backend to be implemented. For example, QQ channel's sharing function can send data through the server, then return "true" to let the server handle the relevant logic
- [Optional] needOpenid2Uid function, which implements the conversion of MSDK Openid in MSDKFriendReqInfo.user to the user ID of the channel

2.2.2 Description of callback fields

For the description of the callback function, please refer to [Client Plugin Development Rules] (../Access/ClientDevRules.md#33-Interface Callback Description)

observerID Callback function ID, which is generally filled in (except for the friend query method), just filled in wth observerID passed in by the channel method. The observerID of the friend query method is kObserverIDQueryFriend
ret return struct
- For common methods (except the friend query method), the return result is InnerBaseRet
- For the friend query method, the return result is InnerFriendRet. Fill the friend information into InnerFriendRet.friendInfoList
- InnerPersonInfo is a friend information struct
  - `openid, the user's MSDK Openid; for channels, it is generally left blank
  - userName, the user's nickname, which can be empty
  - gender, the user's gender, which can be empty
  - pictureUrl, the user's avatar, which can be empty
  - country, the user's country, which can be empty
  - province, the user's province, which can be empty
  - city, the user's city, which can be empty
  - language, the user's language, which can be empty
methodNameID Function ID defined by MSDK, used to define the callback method
- kMethodNameShareToWall is the sharing method's ID
- kMethodNameSendMessageToFriend is the message sending method's ID
- kMethodNameQueryFriend is the friend query method's ID
- kMethodNameAddFriend is the friend adding method's ID

2.2.3 MSDKFriendDelegate protocol

share function

Implement the sharing function. Share messages to the information wall, such as WeChat Moment, QZone, Facebook, information is basically visible to all friends.

Call the channel's sharing function. It is only needed to return "success" or "failure".

  - (void)share:(const MSDKFriendReqInfo &)reqInfo params:(MSDKBaseParams &)params observerID:(unsigned int)observerID {    
  // Call the channel sharing logic    
  ...    

  // Return "Share the message successfully"    
  InnerBaseRet ret(MSDKError::SUCCESS);    
  ret.methodNameID = params.methodID;    
  MSDKInnerObserverHolder<InnerBaseRet>::CommitToTaskQueue(ret, observerID, params.seqID);    
  }

sendMessage function

Implement the message sending function. Send a message to one or more specific players and present it in the channel app in the form of chat record.

Call the message sending function of the channel. It is only needed to return "success" or "failure".

  - (void)sendMessage:(const MSDKFriendReqInfo &)reqInfo params:(MSDKBaseParams &)params observerID:(unsigned int)observerID {    
  // Call the channel's message sending logic    
  ...    

  // Return "Send the message successfully"    
  InnerBaseRet ret(MSDKError::SUCCESS);    
  ret.methodNameID = params.methodID;    
  MSDKInnerObserverHolder<InnerBaseRet>::CommitToTaskQueue(ret, observerID, params.seqID);    
  }

isBackendSupported function

Whether to send data to the backend for implementation. For example, if the sharing function of the QQ channel can be sent by the server, the channel returns "YES" to let the server handle the relevant logic.

MSDK currently does not support the backend call of the friends function in the open platform. If your game needs support for this function, please contact MSDK for processing. Direct return is currently not supported.
```
  - (BOOL)isBackendSupported:(int)methodID type:(int)type seqId:(NSString *)seqId {    
  //  Return "NO ", indicating that the friends function does not support being called by the backend    
  return NO;    
  }
```

queryFriends function

Implement the function of querying friends, generally including: in-game friends, and social friends

Call the channel's friend-getting function. Return the friends list or return "failure" directly.

  - (void)queryFriends:(const MSDKQueryFriendsRequest &)reqInfo params:(MSDKBaseParams &)params {    
  // Return "Not supported"    
  InnerFriendRet ret(MSDKError::NOT_SUPPORT);    
  ret.methodNameID = params.methodID;    
  MSDKInnerObserverHolder<InnerFriendRet>::CommitToTaskQueue(ret, kObserverIDQueryFriend, params.seqID);    
  }

addFriend function

Implement the channel's friend adding function. For example, the player can add friends in Facebook by calling the interface.

Call the channel's friend adding function. It is only needed to return "success" or "failure".

  - (void)addFriend:(const MSDKFriendReqInfo &)reqInfo params:(MSDKBaseParams &)params observerID:(unsigned int)observerID {    
  //  Return "Not supported"    
  InnerBaseRet ret(MSDKError::NOT_SUPPORT);    
  ret.methodNameID = params.methodID;    
  MSDKInnerObserverHolder<InnerBaseRet>::CommitToTaskQueue(ret, observerID, params.seqID);    
  }

needOpenid2Uid function

Implement the conversion of MSDK Openid in 'MSDKFriendReqInfo.user' to the user ID of the channel

MSDK currently does not support the Openid conversion function of the open platform. Please use the game's own backend interface to convert Openid. Please return "false" directly if not needed.
```
  - (BOOL)needOpenid2Uid:(int)methodId reqInfo:(const MSDKFriendReqInfo &)reqInfo seqId:(NSString *)seqId{    
  //  Return "Don't need conversion"    
  return false;    
  }
```
[info] For details, please refer to Demo Code

III. Plugin server development

For how to get in-game friends' relationships, MSDK provides two ways:

MSDK helps the plugin server to host the in-game friends' relationships of the standard channels that MSDK has already supported. The plugin server does not need to implement the friend relationship interface ;
For channels not supported by MSDK, the plugin server needs to implement the friend relationship getting interface for MSDK to call.

The two ways are described in detail as follows:

3.1 MSDK hosts in-game friends' relationships

To enable MSDK to host in-game friends' relationships, it is needed that the client plugin must pass the channel information of the channel to be hosted in case of login

Take the Garena channel as an example. If you want to enable MSDK to host the friend relationship of the Facebook sub-channel under Garena, At login, it is needed to not only pass the channel information of Garena via 'channel_info' but also pass the channel information of Facebook according to the specifications.

{    
    "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"    
}

This means that channel_info needs to include the channel information required for the authentication of the main channel, the channel information required for the authentication of the sub-channel, and the identifier of the sub-channel. The 'channel_info' specification can be summarized as follows:

"channel_info": {    
    "token": "garena token",  // The channel information required for the authentication of the main channe. Different channels contain different fields    
    "sub_channelid": 4,  // The channel ID of the channel to be hosted in MSDK. For detailed mapping relationship, please see the table below.    
    "sub_channel_info": {  // The information required for the authentication of the channel needing to be hosted. Different channels contain different fields. For the detailed format, please see the table below     
        "access_token": "facebook token"    
    }    
}

The list of channels whose friend relationship can be hosted by MSDK currently is as follows:

Channel name	Channel ID (sub_channelid)	The information required for the authentication of the channel (sub_channel_info)
Facebook	4	access_token

3.2 The plugin server implements the friend-getting interface

If the channel supports the friends list function, MSDK can call the friend-getting interface implemented by the plugin server to provide the friends list function for the game.

The plugin server needs to implement the friend-getting interface according to the following specifications:

3.2.1 Interface name

Interface name (/friend/friend_list/ can be configured in the management console)

3.2.2 Request parameters

Parameter	Type	Description	Optional or required
appid	string	App ID	Required
uid	string	Third-party channel's user identifier	Required
token	string	third-party channel's token	Required
page	uint	Page number	Required
page_size	uint	How many pieces are contained in per page?	Required
extraJson	json	Additional information	Optional

3.2.3 Return parameters

Parameter	Type	Description	Optional or required
ret	uint	Return code, 0-success, other-failure	Required
msg	string	Detailed description of the return result	Required
count	uint	Total number	Required
page	uint	Page number	Required
page_size	uint	How many pieces are contained in per page?	Required
list	array	friends list	Required
extraJson	json	User-defined additional information	Optional

Description of objects in "list":

Parameter	Type	Description	Optional or required
uid	string	Third-party channel's user identifier	Required
gender	uint	Gender, 0: Undefined, 1: Male, 2: Female	Optional
birthdate	string	Date of birth, format "YYYY-MM-DD"	Optional
user_name	string	The user's nickname	Required
picture_url	string	Avatar address	Required
extraJson	json	User-defined additional information for every friend	Optional

3.2.4 Request example

Request

 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    
 }

Response

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

Friend