05/15/2024 15:19:45

Group Module

I. Overview

MSDK Group module; only WeChat and QQ support the module function.

Major functions include: create a group, join the existing group, get group state, get group relations, unbind a group, bind a group, remind the union president to build a group, get the list of groups created by the union president, and send group message; where, sending group message is WeChat channel's unique function, while QQ channel's unique functions include: bind a group, remind the union president to build a group, get the list of groups created by the union president.

The union group's process

Permission application description:

1. QQ:
   Follow the path below to apply for login Feiying system (if you want to access the Intranet, you can contact the contact persons of Tencent operations or products to assist in the application). Path: on the left navigate bar of Feiying, find "MSDK Access"—>"Special Permission Application"—>"QQ Join and Bind Groups", and fill in the corresponding information.
   Submit the group-binding request form to the QQ Game Center's contact person, asking for arranging the manpower to configure IDIP and do other matters.
   PS: Each game shall have a corresponding contact person, who is the game's Tencent operations/products contact person. Never accessed to IDIP, the system can return Error code 221008.
   

2. WeChat:
   Contact wxgame (WeChat Games Assistant) and provide the game's name and AppID to apply for enabling the permission.
   

Precautions on the ability of QQ joining and binding groups:

Before verifying the ability to join and bind groups, you need to make sure that the game side has completed the development of the IDIP interface (contact IDIP Assistant for scheduling) and the QQ group joining and binding platform has completed the development of the IDIP query interface. (Purpose: Used for the QQ group joining and binding platform to query whether the player is a guild member/president and query other information. After the development of the IDIP interface is completed, please contact carsonyuan for scheduling.)

II. Access Guide

2.1 Register Callback

1) Function Description

Receive MSDK Group module's callback, The game needs to register a callback function for processing.

2) Interface Declaration

/// <summary>
/// group's callback interface 
/// </summary>
public static event OnMSDKRetEventHandler<MSDKGroupRet> GroupRetEvent;

class MSDKGroupObserver 
{
public:
    // The group's callback interface 
    virtual void OnLoadGroupData (const MSDKGroupRet &groupRet) {}; 
};

3) Demo code

MSDKGroup.GroupRetEvent += OnGroupRetEvent;

public void OnGroupRetEvent (MSDKGroupRet groupRet) 
{
    string methodTag = "";
    if (groupRet.MethodNameId == (int) MSDKMethodNameID.MSDK_GROUP_CREATE) {
        methodTag = "CreateGroup";
    } else if (groupRet.MethodNameId == (int) MSDKMethodNameID.MSDK_GROUP_BIND) {
        methodTag = "BindGroup";
    } else if (groupRet.MethodNameId == (int) MSDKMethodNameID.MSDK_GROUP_GET_GROUP_LIST) {
        methodTag = "GetGroupList";
    } else if (groupRet.MethodNameId == (int) MSDKMethodNameID.MSDK_GROUP_GET_GROUP_STATE) {
        methodTag = "GetGroupState";
    } else if (groupRet.MethodNameId == (int) MSDKMethodNameID.MSDK_GROUP_JOIN) {
        methodTag = "JoinGroup";
    } else if (groupRet.MethodNameId == (int) MSDKMethodNameID.MSDK_GROUP_UNBIND) {
        methodTag = "UnbindGroup";
    } else if (groupRet.MethodNameId == (int) MSDKMethodNameID.MSDK_GROUP_REMIND_TO_BIND) {
        methodTag = "RemindToBind";
    } else if (groupRet.MethodNameId == (int) MSDKMethodNameID.MSDK_GROUP_SEND_GROUP_MESSAGE) {
        methodTag = "SendGroupMessage";
    } else if (groupRet.MethodNameId == (int) MSDKMethodNameID.MSDK_GROUP_GET_GROUP_RELATION) {
        methodTag = "GetGroupRelation";
    }

    SampleInstance.showRetDialog (methodTag, groupRet); 
}

//Need to remove the listener when destroying it
private void OnDestroy()
{
    MSDKGroup.GroupRetEvent -= OnGroupRetEvent; 
}

MSDKGroup::SetGroupObserver(new MyGroupObserver());
class MyGroupObserver: public MSDKGroupObserver 
{
    void OnLoadGroupData (const MSDKGroupRet &groupRet) {
        handleCallBack(groupRet, groupRet.methodNameID);
    }
}

4) Data Structure

MSDKGroupRet explanation
Inherited from MSDKBaseRet; contain the basic information

2.2 Create Group

1) Function Description

① On WeChat, the union president creates a WeChat group;
② On QQ, the union president creates a QQ group. In the test environment, QQ needs to pass in areaID.
Returns and results:
When createGroup's retCode is 0, this means that the group is created successfully. You can see the new group's information on QQ/WeChat on the mobile device.5.10 and higher versions optimize the callback of QQ group creation. You can get the information of the newly created groups through the GroupId and GroupName of MSDKGroupRet.

Precautions:
1、WeChat and QQ platforms have a limit on the number of groups added to the same account. If the number exceeds the limit, an error will be reported when the relevant interface of MSDK is invoked;
2、Union ID is recommended to be random, not being incremental or having regularity.

2) Interface Declaration

public static void CreateGroup (string unionID, string unionName = "", string roleName = "", string zoneID = "", string roleID = "", string extraJson = "")

static void CreateGroup (String unionID, String unionName ="", String roleName ="", String zoneID ="", String roleID = "", String extraJson= "");

3) Parameter Description

4) Demo code

if (_mCurLoginChannel.Equals("QQ")) {
    string unionID = "1234";
    string unionName = "unionName";
    string roleName = "roleName";
    string zoneID = "5678";
    string roleID = "roleID";
    string extraJson = "{\"areaID\":\"1\"}"; //areaID is required;in the test environment, it is needed to pass in the value agreed with IDIP through areaID; and in the release environment, it is needed to pass in a fixed value of 2 through areaID.
    MSDKGroup.CreateGroup(unionID, unionName, roleName, zoneID, roleID，extraJson);
} else if (_mCurLoginChannel.Equals("WeChat")) {
    string unionID = "unionID";
    string unionName = "unionName";
    string roleName = "roleName";
    MSDKGroup.CreateGroup(unionID, unionName, roleName);
}

if (mCurChannel == "QQ") {
    string unionID = "1234";
    string unionName = "unionName";
    string roleName = "roleName";
    string zoneID = "5678";
    string roleID = "roleID";
    string extraJson = "{\"areaID\":\"1\"}"; ////areaID is required;in the test environment, it is needed to pass in the value agreed with IDIP through areaID; and in the release environment, it is needed to pass in a fixed value of 2 through areaID.
    MSDKGroup::CreateGroup(unionID, unionName, roleName, zoneID, roleID, extraJson);
} else if (mCurChannel == "WeChat") {
    string unionID = "unionID";
    string unionName = "unionName";
    string roleName = "roleName";
    MSDKGroup::CreateGroup(unionID, unionName, roleName);
}

2.3 Join Group

1) Function Description

Union members join existing groups.
① WeChat: Join a WeChat group. MSDK V5.8 and earlier versions only requires the union members to fill in unionID. MSDK V5.9 and later versions support setting a nickname through the extension field 'nickName' when a union member joins a union group.
② QQ: Join a QQ group. Since a union member can join multiple groups on QQ, he or she is required to fill in groupID (QQ group ID) as well as zoneID, roleID and nickName. In the test environment, QQ needs to pass in areaID (the user needs to keep the information of creating the group)
Returns and results:
When JoinGroup's retCode is 0, this indicates joining the group successfully. QQ and WeChat terminals can show the corresponding group which a union member has joined successfully.

Precautions:
1、WeChat and QQ platforms have a limit on the number of groups added to the same account. If the number exceeds the limit, an error will be reported when the relevant interface of MSDK is invoked;

2) Interface Declaration

public static void JoinGroup (string unionID, string zoneID = "", string roleID = "", string groupID = "", string extraJson = "")

static void JoinGroup (String unionID, String zoneID = "", String roleID = "", String groupID = "", String extraJson = "");

3) Parameter Description

4) Demo code

if (_mCurLoginChannel.Equals("QQ")) {
    string unionID = "1234";
    string zoneID = "5678";
    string roleID = "roleID";
    string groupID = "1234567890";
    string extraJson = "{\"areaID\":\"1\"}"; //areaID is required;in the test environment, it is needed to pass in the value agreed with IDIP through areaID; and in the release environment, it is needed to pass in a fixed value of 2 through areaID.
    MSDKGroup.JoinGroup(unionID, zoneID, roleID, groupID, extraJson);
} else if (_mCurLoginChannel.Equals("WeChat")) {
    string unionID = "unionID";
    MSDKGroup::JoinGroup(unionID);
}

if (mCurChannel == "QQ") {
    string groupID = "1234567890";
    string unionID = "1234";
    string zoneID = "5678";
    string roleID = "roleID";
    string extraJson = "{\"areaID\":\"1\"}"; //areaID is required;in the test environment, it is needed to pass in the value agreed with IDIP through areaID; and in the release environment, it is needed to pass in a fixed value of 2 through areaID.
    MSDKGroup::JoinGroup(unionID, zoneID, roleID, groupID, extraJson);
} else if (mCurChannel == "WeChat") {
    string unionID = "unionID";
    MSDKGroup::JoinGroup(unionID);
}

2.4 Get Group State

1) Function Description

View the state of the union binding the group.
① WeChat: only need to input the queried union information unionID
② QQ: need unionID and zoneID; query information about the state of the union binding the group Return information and result:
In the return code, 0 indicates not binding any group, 1 indicates that the union has bound a group.

2) Interface Declaration

public static void GetGroupState (string unionID, string zoneID = "", string extraJson = "")

static void GetGroupState (String unionID, String zoneID = "", String extraJson = "") ;

3) Parameter Description

4) Demo code

if (_mCurLoginChannel.Equals("QQ")) {
    string unionID = "1234";
    string zoneID = "5678";
    MSDKGroup.GetGroupState(unionID, zoneID);
} else if (_mCurLoginChannel.Equals("WeChat")) {
    string unionID = "unionID";
    MSDKGroup.GetGroupState(unionID);
}

if (mCurChannel == "QQ") {
    string unionID = "1234";
    string zoneID = "5678";
    MSDKGroup::GetGroupState(unionID, zoneID);
} else if (mCurChannel == "WeChat") {
    string unionID = "unionID";
    MSDKGroup::GetGroupState(unionID);
}

2.5 Get Group Relations

1) Function Description

View the identity of the user in the specified group.
① WeChat: fill the unionID
② QQ: fill the specified groupID
Returned information and results are as follows:

2) Interface Declaration

public static void GetGroupRelation (string targetID, string extraJson = "")

static void GetGroupRelation (String targetID, String extraJson = "");

3) Parameter Description

4) Demo code

if (_mCurLoginChannel.Equals("QQ")) {
    string groupID = "groupID1234";
    MSDKGroup.getGroupRelation (groupID); 
} else if (_mCurLoginChannel.Equals("WeChat")) {
    string unionID = "unionID1234";
    MSDKGroup.GetGroupRelation (unionID); 
}

if (mCurChannel == "QQ") {
    string groupID = "QQGroupID1234"; 
    MSDKGroup:: GetGroupRelation (groupID); 
} else if (mCurChannel == "WeChat") {
    string unionID = "WeChatUnionID1234"; 
    MSDKGroup:: GetGroupRelation (unionID); 
}

2.6 Unbind Group

1) Function Description

Unbind the target group.
1) WeChat: only need to fill with unionID
2) QQ: fill with the previously recorded unionID, unionName, zoneID and roleID in order
Return information and result:
Return the return code about the information of unbinding the group successfully through querying getGroupState. If the return code shows that the union where the user does not bind any group, this can verify that the user unbinds group successfully.

2) Interface Declaration

public static void UnbindGroup (string unionID, string unionName = "", string zoneID = "", string roleID = "", string extraJson = "")

static void UnbindGroup (String unionID, String unionName = "", String zoneID = "", String roleID = "", String extraJson = "");

3) Parameter Description

4) Demo code

if (_mCurLoginChannel.Equals("QQ")) {
    string unionID = "1234";
    string unionName = "unionName";
    string zoneID = "5678";
    string roleID = "roleID";
    string extraJson = "{\"areaID\":\"1\"}"; //areaID is required;in the test environment, it is needed to pass in the value agreed with IDIP through areaID; and in the release environment, it is needed to pass in a fixed value of 2 through areaID.
    MSDKGroup.UnbindGroup(unionID, unionName, zoneID, roleID，extraJson);
} else if (_mCurLoginChannel.Equals("WeChat")) {
    string unionID = "unionID";
    MSDKGroup.UnbindGroup(unionID);
}

if (mCurChannel == "QQ") {
    string unionID = "1234";
    string unionName = "unionName";
    string zoneID = "5678";
    string roleID = "roleID";
    string extraJson = "{\"areaID\":\"1\"}"; //areaID is required;in the test environment, it is needed to pass in the value agreed with IDIP through areaID; and in the release environment, it is needed to pass in a fixed value of 2 through areaID.
    MSDKGroup::UnbindGroup(unionID, unionName , zoneID , roleID, extraJson);
} else if (mCurChannel == "WeChat") {
    string unionID = "unionID";
    MSDKGroup::UnbindGroup(unionID);
}

2.7 Remind the Union President to Build a Group (unique to QQ channel)

1) Function Description

QQ can remind the union president to build a group.
The union president pays attention to the "QQ mobile game" service number. After the system returns the function is implemented successfully, the union president receives the message in the service number.The frequency limit restricts that an account can receive one piece a day.

2) Interface Declaration

public static void RemindToBindGroup (string unionID, string zoneID, string roleID, string roleName, string leaderOpenID, string leaderRoleID, string extraJson = "")

static void RemindToBindGroup (String unionID, String zoneID, String roleID, String roleName, String leaderOpenID, String leaderRoleID, String extraJson = "");

3) Parameter Description

4) Demo code

string unionID = "1234";
string zoneID = "5678";
string roleID = "roleID";
string roleName = "roleName";
string leaderOpenID = "leaderOpenID";
string leaderRoleID = "leaderRoleID";
string extraJson = "{\"areaID\":\"1\"}";/ //areaID is required;in the test environment, it is needed to pass in the value agreed with IDIP through areaID; and in the release environment, it is needed to pass in a fixed value of 2 through areaID.
MSDKGroup.RemindToBindGroup(unionID, zoneID, roleID, roleName, leaderOpenID, leaderRoleID extraJson);

string unionID = "1234";
string zoneID = "5678";
string roleID = "roleID";
string roleName = "roleName";
string leaderRoleID = "leaderRoleID";
string leaderOpenID = "leaderOpenID";
string extraJson = "{\"areaID\":\"1\"}"; //areaID is required;in the test environment, it is needed to pass in the value agreed with IDIP through areaID; and in the release environment, it is needed to pass in a fixed value of 2 through areaID.
MSDKGroup::RemindToBindGroup(unionID, zoneID, roleID, roleName, leaderOpenID, leaderRoleID, extraJson);

2.8 Bind A Group (unique to QQ channel)

1) Function Description

On QQ, the union president binds the existing QQ group, before this interface is called, it is needed to first call the GetGroupList() interface to draw the list of created groups.
Return information and result:
Return the return value information of binding group successfully. Through calling getGroupState, you can see that you have been bound to the group. This achieves verification.

2) Interface Declaration

public static void BindGroup (string unionID, string zoneID, string roleID, string groupID, string groupName, string extraJson = "")

static void BindGroup (String unionID, String zoneID, String roleID, String groupID, String groupName, String extraJson = "");

3) Parameter Description

4) Demo code

string unionID = "1234";
string zoneID = "5678";
string roleID = "roleID";
string groupID = "1234567890";
string groupName = "groupName";
string extraJson = "{\"areaID\":\"1\"}"; //areaID is required;in the test environment, it is needed to pass in the value agreed with IDIP through areaID; and in the release environment, it is needed to pass in a fixed value of 2 through areaID.
MSDKGroup.BindGroup(unionID, zoneID, roleID, groupID, groupName, extraJson);

string groupID = "1234567890";
string groupName = "groupName";
string unionID = "1234";
string zoneID = "5678";
string roleID = "roleID";
string extraJson = "{\"areaID\":\"1\"}"; //areaID is required;in the test environment, it is needed to pass in the value agreed with IDIP through areaID; and in the release environment, it is needed to pass in a fixed value of 2 through areaID.
MSDKGroup::BindGroup(unionID, zoneID, roleID, groupID, groupName, extraJson);

2.9 Get the List of Groups Created by the Union President (unique to QQ channel)

1) Function Description

On QQ side, view the list of groups owned by the union president.
Return information:
GroupInfo in the return value records the list of groups owned by the union president, where each group record contains the groupID and groupName of the group

2) Interface Declaration

public static void GetGroupList ()

static void GetGroupList ();

3) Demo code

MSDKGroup.GetGroupList();

MSDKGroup::GetGroupList();

4) Data structure

MSDKGroupInfo explanation

2.10 Send Group Message (unique to WeChat channel)

1) Function Description

On WeChat side, send messages to the group chat. If the information is sent successfully, the message record can be seen on the WeChat side. A single user can send up to 100 pieces of messages per day in the same group.

2) Interface Declaration

public static void SendGroupMessage (MSDKGroupMessage groupMessage, string unionID)

static void SendGroupMessage (const MSDKGroupMessage &groupMessage, String unionID);

3) Parameter Description

MSDKGroupMessage explanation

1、 QQ

2、 WeChat

4) Demo code

1、QQ

MSDKGroupMessage info = new MSDKGroupMessage();
info.Title = "title";
info.Link = "http://www.qq.com";
info.Desc = "desc";
info.ExtraJson = "{\"imageUrl\": \"https://avatars0.githubusercontent.com/u/3755338?s=460&v=4\",\"param\": \"11\"}";

string ID = "group_openid";
MSDKGroup.SendGroupMessage(info, ID);

MSDKGroupMessage groupMessage;
groupMessage.Title = "title";
groupMessage.Link = "http://www.qq.com";
groupMessage.Desc = "desc";
groupMessage.ExtraJson = "{\"imageUrl\": \"https://avatars0.githubusercontent.com/u/3755338?s=460&v=4\",\"param\": \"11\"}";

string ID = "group_openid";
MSDKGroup::SendGroupMessage(groupMessage, ID);

2、WeChat

MSDKGroupMessage info = new MSDKGroupMessage();
info.Title = "title";
info.Link = "https://game.weixin.qq.com/cgi-bin/act?noticeid=90103953&actid=7006&k=Q6EgQ_8DgubBRXGb1vmTBw&q=0&jsapi_ticket=1&hongbaoid=8CF558E6633CCB020796260075B95465#wechat_redirect";
info.Desc = "desc";
info.Type = 1;
info.ActionReport = 1;
info.ExtraJson = "{\"messageExt\": \"test1\",\"mediaTagName \": \"test2\"}";

string ID = "Union ID";
MSDKGroup.SendGroupMessage(info, ID);

MSDKGroupMessage groupMessage;
groupMessage.Title = "title";
groupMessage.Link = "https://game.weixin.qq.com/cgi-bin/act?noticeid=90103953&actid=7006&k=Q6EgQ_8DgubBRXGb1vmTBw&q=0&jsapi_ticket=1&hongbaoid=8CF558E6633CCB020796260075B95465#wechat_redirect";
groupMessage.Desc = "desc";
groupMessage.Type = 1;
groupMessage.ActionReport = 1;
groupMessage.ExtraJson = "{\"messageExt\": \"test1\",\"mediaTagName \": \"test2\"}";

string ID = "Union ID";
MSDKGroup::SendGroupMessage(groupMessage, ID);

III. FAQs

3.1 Detailed description of MSDKUnionInfo

3.2 Precautions on the ability of QQ joining and binding groups:

(1)A uion ID can only be bound to one QQ group;

(2) The QQ group joining and binding platform uses AppID+zoneID+uion ID as the unique identifier. If the game side wants to combine two servers into one, it is needed to pay attention to the logic processing after the servers are combined, that is, the mapping processing of the player's zoneID before the servers are combined and the player's zoneID after the servers are combined. If a guild was created in the 101 partition before the servers are combined, no matter which partition the user is in later on, the partition ID of the 101 partition shall be transmitted;

(3) If the user disbands the guild's QQ group, the guild and the guild's QQ group will not be automatically unbound. You can cancel the binding relationship by the following methods. If you have not performed any of the following operations, the binding relationship will not disappear automatically :

• The guild president calls the unbinding interface to dissolve the group relationship;
  
• When a guild member calls the group- joining interface, the group ID cannot be queried at this time, and the binding relationship will be unbound by default;
  

(4) After the guild president transfers the group to another guild, the new guild president can also perform unbinding operations;

(5) areaID needs to be passed in the extraJson field. It is strictly case-sensitive. In the test environment, it is only needed to pass in the value agreed with IDIP. In the formal environment, it is needed to pass in 2;

3.3 Error code

(1) QQ group function's return code;
(2) WeChat group function's return code.