Outline

The relation chain module is an information query service which is provided by MSDK and is based on mobile QQ and WeChat friends' relations. The relation chain module provides the following functions:

1)Query the personal information (PersonInfo): nickname (nickname), OpenId(openId), small avatar 40x40(pictureSmall), mid-sized avatar 60x60(pictureMiddle), large avatar 100x100(pictureLarge)
Note: since there are restrictions in the mobile QQ, if the head portrait is returned in only two modes (namely, 40x40 and 100x100), head portrait of 40x40 will be returned for the medium size setting of mobile QQ.

2)Query friends' information：only support to query the information of friends who have played the current game. The detailed information of each friend is the same with his or her personal detailed information (PersonInfo)

3)Add QQ friends: You can complete the function of adding friends in the game through the interface Add QQ friends

You can use the function of querying personal information and querying friends' information in the following scenes:

4)Game leaderboard（take the friends leaderboard of "Sword Heroes Fate" as an example）

QQ friends information call interface : WGQueryQQGameFriendsInfo

Function 1: Call WGQueryQQGameFriendsInfo to get the data of QQ game friends

Function 2: Gift: which is a backend sharing function. Its feature is to be able to directly share messages to friends through the server without launching mobile QQ. For details, you can refer to the Share Module's "mobile QQ backend sharing"

Function 3: game entrance for mobile QQ friends

Function 4: invite friends: which is a sharing function to share messages to QQ session. For details, please refer to the Share Module's "QQ structured sharing"

WeChat friends information call interface : WGQueryWXGameFriendsInfo

Function 1: Call WGQueryWXGameFriendsInfo to get the data of WeChat game friends

Function 2: Gift: which is a backend sharing function. Its feature is to be able to directly share messages to friends through the server without launching WeChat. For details, please refer to the Share Module's "WeChat backend sharing"

Function 3: game entrance for WeChat game friends

Function 4: invite friends: which is a sharing function to share messages to WeChat session. For details, please refer to the Share Module's " WeChat structured sharing"

5)Add qq friends

Access Guide

1 Preconditions

1)You have completed initialization according to the initialization module's description initialization。

2)Confirm that the user has completed mobile QQ/WeChat authorized login

2 Refer to demos

1)For mobile QQ personal information examples, please refer to MSDKDemo/LoginSucceedVC.mm file's onClickPersonalInfo method.

2)For mobile QQ friends examples, refer to MSDKDemo/LoginSucceedVC.mm file's onClickGoodFriendsInfo method.

3)For WeChat personal information examples, please refer to MSDKDemo/LoginSucceedVC.mm file's onClickPersonalInfo method.

4)For mobile WeChat friends examples, refer to MSDKDemo/LoginSucceedVC.mm file'sonClickGoodFriendsInfo method.

Query personal information

Outline

1)Mobile QQ user (WGQueryQQMyInfo): After the user is authorized via mobile QQ, the game requires the user's nickname, avatar and other information and can call WGQueryQQMyInfo to get the user's personal information, including: nickname, openId, small avatar (PictureSmall), mid-sized avatar (pictureMiddle), and large avatar (pictureLarge).

2)After the WeChat user (WGQueryWXMyInfo) has been authorized for use of WeChat, the game needs the user information like nickname and picture. WGQueryWXMyInfo may be called. Here, personal information includes: nickname(nickname), OpenId( openId), small picture(pictureSmall), middle picture(pictureMiddle), large picture(pictureLarge).

Registration callback

1)Function description

To receive msdk's relation chain callback, the game needs to register the callback function. When registering the callback, the game is required to implement the “OnRelationNotify” virtual method of WGPlatformObserver class.

2)Interface declaration

void OnRelationNotify(RelationRet& relationRet)

3)Parameter description

4)Return value

None

5)Demo code

void MyObserver::OnRelationNotify(RelationRet &relationRet)
{
    NSLog(@"relation callback");
    NSLog(@"count == %lu",relationRet.persons.size());
    NSMutableArray *personInfoArr = [NSMutableArray new];
    for (int i = 0; i < relationRet.persons.size(); i++)
    {
        PersonInfo logInfo = relationRet.persons[i];
        NSMutableDictionary *personInfoDict = [NSMutableDictionary new];
        NSString *nickName = [NSString stringWithCString:(const char*)logInfo.nickName.c_str() encoding:NSUTF8StringEncoding];
        NSString *openID = [NSString stringWithCString:(const char*)logInfo.openId.c_str() encoding:NSUTF8StringEncoding];
        NSString *pictureSmall = [NSString stringWithCString:(const char*)logInfo.pictureSmall.c_str() encoding:NSUTF8StringEncoding];
        NSString *pictureMiddle = [NSString stringWithCString:(const char*)logInfo.pictureMiddle.c_str() encoding:NSUTF8StringEncoding];
        NSString *pictureLarge = [NSString stringWithCString:(const char*)logInfo.pictureLarge.c_str() encoding:NSUTF8StringEncoding];
        NSString *gpsCity = [NSString stringWithCString:(const char*)logInfo.gpsCity.c_str() encoding:NSUTF8StringEncoding];
        NSString *country = [NSString stringWithCString:(const char*)logInfo.country.c_str() encoding:NSUTF8StringEncoding];
    }
}

6)Special description

None

7)Term interpretation

None

Call interfaces

1)Function description

The game can query the personal information by calling WGQueryQQMyInfo/WGQueryWXMyInfo interface, so as to get nickname(nickname), OpenId( openId), small avatar 40x40(pictureSmall), mid-sized avatar 60x60(pictureMiddle), large avatar 100x100(pictureLarge)

2)Interface declaration

bool WGQueryQQMyInfo();
bool WGQueryWXMyInfo();

3)Parameter description

None

4)Return value

None, the result is called back through RelationEvent. As for callback settings, please refer to Registration Callback

5)Demo code

if (self.platform == 2)//eplatform_QQ
{
    WGPlatform::GetInstance()->WGQueryQQMyInfo();
}
else if (self.platform == 1)//eplatform_Weixin
{
    WGPlatform::GetInstance()->WGQueryWXMyInfo();
}

6)Special description

The personal information doesn't contain OpenId information. If you need OpenId information, you can get it through the login module's token-getting interface WGGetLoginRecord. Callbacks of querying personal information and querying game friends can be distinguished via eRelationRetType.

7)Term interpretation

None

Query game friends' information

Outline

1)Mobile QQ user (WGQueryQQGameFriendsInfo) After the user gets authorization through mobile QQ, the user can get friends' information (such as friends' score leaderboard ) in the game through WGQueryQQGameFriendsInfo. As for friends' information, please refer to the personal information

2)WeChat user (WGQueryWXGameFriendsInfo) After the user gets authorization through WeChat, the user can get friends' information (such as friends' score leaderboard ) in the game through WGQueryWXGameFriendsInfo. As for friends' information, please refer to the personal information

Registration callback

This interface and the personal information query interface use the same callback. If the callback has been set, it is not needed to repeat setting it. If the callback is not set, please check if the callback setting RelationRet object's persons attribute is a List, in which each PersonInfo object is a friend's information. A friend's information includes: nickname, openId, small avatar 40x40(pictureSmall), mid-sized avatar 60x60(pictureMiddle), large avatar 100x100(pictureLarge).

Call interfaces

1)Function description

The game can query the personal information by calling WGQueryQQGameFriendsInfo/WGQueryWXGameFriendsInfo interface, so as to get nickname(nickname), OpenId(openId), small avatar 40x40(pictureSmall), mid-sized avatar 60x60(pictureMiddle), large avatar 100x100(pictureLarge).

2)Interface declaration

bool WGQueryQQGameFriendsInfo();
bool WGQueryWXGameFriendsInfo();

3)Parameter description

None

4)Return value

None, the result is called back through RelationEvent. As for callback settings, please refer to Registration Callback

5)Demo code

if (self.platform == 2)//eplatform_QQ
{
    WGPlatform::GetInstance()->WGQueryQQGameFriendsInfo();
}
else if (self.platform == 1)//eplatform_Weixin
{
    WGPlatform::GetInstance()->WGQueryWXGameFriendsInfo();
}

6)Special description

1)In order to prevent the failure of getting the personal information (such as avatar, name), friends' information (such as avatar, name) from resulting in the failure of logging in the game, please set querying the personal information and querying friends' information as the non-critical path.

2)In mobile QQ, the result of querying game friends' does not contain the user's own information; but in WeChat, the result contains the user's own information.

3)V3.3.21 version starts adding the user's unauthorized error codes in the relationship callback interface;if the user does not authorize the relationship permission, then relationRet.flag = eFlag_UnPermission (-9) in the callback interface OnRelationNotify.

4)Starting from version V3.3.28 `WGQueryWXGameFriendsInfo` the client interface of WeChat in-game friend information retrieval function, adds returning the `friendRemark` (remark name) field.

The test environment and release environment of MSDK V3 are compatible with the old scheme by default (`nickname` gives priority to using WeChat friend remarks and does not return the `friendRemark` field). If the game needs to switch to the new scheme (`nickname` corresponds to WeChat nickname, and `friendRemark` corresponds to WeChat in-game friend remarks), it needs to contact MSDK to update the configuration for the game to enable the new scheme.

7)Term interpretation

Game friends: players who are playing the current game

Non-critical path: refer to a saying of not affecting the game's login process; msdk defines mobile QQ\WeChat's login process as the critical path. Once the login process is interrupted, this will cause a serious impact on the normal operation of the game.

Add QQ friends

Outline

Players can directly add (launch mobile QQ) other players in the game as QQ friends (multiple clicks will not send multiple applications to add QQ).

Registration callback

No matter whether adding succeeds or fails, the result will be called back to the game through OnShareNotify(ShareRet ret). ret.flag indicates different sharing results. See eFlag for details.

Call interfaces

1)Function description

The player can directly add (launch mobile QQ) game players as QQ friends in the game.

2)Interface declaration

void WGAddGameFriendToQQ(unsigned char* cFopenid, unsigned char* cDesc, unsigned char* cMessage)

3)Parameter description

4)Return value

None

5)Demo code

WGPlatform::GetInstance()->WGAddGameFriendToQQ((unsigned char*)"C1BF66286792F24E166C9A5D27CFB519",
                                               (unsigned char*)"Test the friend adding function",
                                               (unsigned char*)"How are you～");

6)Special description

None

7)Name interpretation

None

FAQ

1. How to differentiate the personal information and game friends information

Note: In 2.18.0i and higher versions, callbacks of querying personal information and querying game friends can be distinguished via the type field of RelationRet

1) If the number of elements in persons list in OnRelationNotify callback’s RelationRet exceeds 1, it must be the game friends information

2)How can we distinguish them when if the personal information and the game friends information both contain one element?

1.Get OnRelationNotify callback’s openId

We can refer to the first element PersonInfo's openId in persons list of RelationRet.

2.Get the current login user's openId

We can get openId by getting local token, and the game can use its own way to get it

3.Compare openId

Same: personal information

Different: game friends information

2. How long will the modified WeChat avatar, friends and other information take effect?

WeChat platform takes into account that the game avatar does not need to be updated in real time. When WeChat avatar is updated, WeChat platform will save the updated avatar into DB for cache, and then synchronize the avatar into the game after a period of time. According to the WeChat platform strategy, the synchronic update time is down to 4 hours and up to 48 hours. WeChat friends’ information is modified in the same way.

The modification of mobile QQ friends information is usually completed synchronously within 1 hour or so.