fusion2.dialog.manageQQGroup

2013年8月14日前创建的“托管模式”应用,不管是否上线均可以直接调用本接口。
2013年8月14日及以后创建的“托管模式”应用,需要申请使用权限。请按照模版提交API接口权限申请(申请方式详见这里),以获取接口调用权限。
“非托管模式”应用不支持调用本接口。

目录

1 功能说明

1. 接口类型:前端JS接口。

2. 接口功能:根据参数“type”传入的值不同,可以实现如下功能:
(1)在应用内创建游戏公会QQ群
(2)用户加入游戏公会QQ群
(3)用户退出游戏公会QQ群邀请用户加入功能
(4)邀请用户加入游戏公会QQ群

3. 功能描述:
(1)在应用界面上放置类似“创建公会QQ群”的按钮,用户点击后,调用本接口,“type”值传入“create”,弹出“创建公会QQ群”弹框。用户可以选择创建新的QQ群,或与现有QQ群进行绑定。
(2)在应用适当的位置放置“邀请加入公会QQ群”按钮,管理员点击后,调用本接口,type”值传入“invite”,弹出“邀请成员加入公会QQ群”弹框。管理员即可邀请其他用户加入公会QQ群。
(3)应用中已经有公会QQ群,在应用中放置“加入公会QQ群”的按钮,用户点击后,调用本接口,“type”值传入“join”,弹出“加入公会QQ群”弹框,用户确定后即可加入。
(4)如果用户已经加入了应用的公会QQ群,在适当的位置放置“退出”按钮,用户点击后,调用本接口,“type”值传入“quit”,弹出“退出公会QQ群”弹框,用户确定后即可退出QQ群。


4. 接口调用限制:
(1)支持的平台:本接口目前仅支持QQ空间平台。
(2)创建QQ群时,根据创建者的等级、是否是QQ会员或超级QQ来限制创建QQ群的数量及QQ群的级别,对应关系如下图所示:
qqgroup_1.png
(3)只有公会会长可以触发应用调用本接口进行创建公会QQ群的操作。
(4)只有群主/管理员可以触发应用调用本接口进行邀请成员加入公会QQ群的操作。

2 场景说明

2.1 创建公会QQ群

应用中在合适的地方放置“创建公会QQ群”的按钮,鼓励用户点击。
用户点击后,应用调用本接口弹出“创建公会QQ群”弹框。

用户可以选择创建新的QQ群,创建的群会自动与公会ID进行绑定。根据调用接口时传入的参数,在界面中显示群名字、群规模、以及是否需要验证。如下图所示:
qqgroup_2.png
用户也可以选择将公会ID与现有的QQ群进行绑定,在界面中显示可以绑定的QQ群,用户只能选择其中的一个QQ群进行绑定。如下图所示:
qqgroup_3.png

创建或绑定成功后,会在界面中返回群名称和群号。如下图所示:
qqgroup_4.png
同时用户会收到QQtips,如下图所示:
qqgroup_6.png
用户点击群号后,会弹出QQ群对话框,提示用户激活新创建的公会QQ群。如下图所示:
qqgroup_5.png

2.2 邀请成员加入公会QQ群

用户创建公会QQ群成功后,会QQtips提示用户可以邀请成员加入。用户也可以在创建的QQ群对话框中,进行邀请成员操作。
用户进行邀请成员操作后,应用调用本接口,弹出“邀请成员加入公会QQ群”弹框,如下图所示:
qqgroup_7.png

用户点击确定发出邀请后,会在界面上提示邀请已发出,如下图所示:
qqgroup_8.png
被邀请的成员就会收到邀请加入QQ群的QQtips,如下图所示:
qqgroup_9.png
成员确认之后,邀请的发起者收到成员加入群的确认QQtips,如下图所示:
qqgroup_10.png

2.3 加入公会QQ群

如果应用中已经有游戏公会QQ群,在游戏公会的适当位置显示公会QQ群以及“加入”按钮。
用户点击“加入”按钮后,应用调用本接口,弹出“加入公会QQ群”弹框,如下图所示:
qqgroup_11.png

用户点击“确定”确认之后,公会QQ群默认需要管理员进行验证审核,弹框提示用户“请求已发出”。此时管理员会收到请求加入的QQtips,如下图所示:
qqgroup_12.png
等待管理员同意审核完成之后,用户才能加入该群,并QQtips提示用户请求通过,如下图所示:
qqgroup_13.png

2.4 退出公会QQ群

如果用户已经加入了游戏公会QQ群,在游戏公会的适当位置显示公会QQ群以及“退出”按钮。
用户点击“退出”按钮后,应用调用本接口,弹出“退出公会QQ群”弹框,如下图所示:
qqgroup_14.png

用户点击“确定”确认之后,弹框提示用户“已成功退出该群”,并QQtips提示用户已退出群,如下图所示:
qqgroup_15.png

3 接口调用说明

调用本前端接口前,应用中应该部署Fusion2的跨域文件以及引用脚本,请参阅:Fusion2文档

3.1 创建公会QQ群

1. 参数说明

参数名称 是否必须 类型 描述
type 必须 string 参数描述:操作类型。

创建公会QQ群,传入的值为“create”。

unionid 必须 string 参数描述:游戏公会ID。

格式限制:请输入800,000,000及以下范围的正整数。

groupname 必须 string 参数描述:创建的公会QQ群的群名。

长度限制:控制在10个汉字以内,超过10个汉字进行截断。

zoneid number 支付营销分区配置说明页面,配置的分区ID即为这里的“zoneid”。

如果应用不分区,则为0。

context string 参数描述:透传参数,用于onSuccess和onCancel回调,以识别请求。

透传方式:调用本接口时传入该参数,onSuccess或onCancel回调时,在JS中使用opt.context即可获取该透传参数(opt为本接口的回调函数形参)。
例如用户操作成功后,会回调onSuccess时获取该参数的值:

onSuccess : function (opt) 
  {       
      alert("Succeeded: " + opt.context);  
  }
onSuccess 参数描述:用户操作成功后的回调方法。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击弹出框中的“确定”按钮,提示成功,弹出框关闭。

onError 参数描述:用户操作失败后的回调方法。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击弹出框中的“确定”按钮,但请求后台失败。失败的返回码详见#4 返回码说明

onCancel 参数描述:用户取消操作后的回调方法。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击取消或弹出框右上角的×按钮,弹出框关闭。用户取消时将同时关闭对话框,因此将先触发onCancel回调再触发onClose回调。

onClose 参数描述:对话框关闭时的回调方法。主要用于对话框关闭后进行UI方面的调整,onSuccess和onCancel则用于应用逻辑的处理,避免过度耦合。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击取消或弹出框右上角的×按钮,弹出框关闭。用户取消时将同时关闭对话框,因此将先触发onCancel回调再触发onClose回调。


2. 调用示例

fusion2.dialog.manageQQGroup({
     type: "create",


     unionid: "123456789",


     groupname: "开发者公会",


     zoneid: "123",


     context: "manage-QQGroup-12345",


     onSuccess: function(opt) {
            alert("QQ群操作成功: " + fusion.JSON.stringify(opt));
     },


     onError: function(opt) {
            alert("QQ群操作失败: " + fusion.JSON.stringify(opt));
     },


     onCancel: function(opt) {
            alert("用户取消: " + fusion.JSON.stringify(opt));
     },


     onClose: function(opt) {
            alert("浮层关闭: " + fusion.JSON.stringify(opt));
     }
});


3. 返回参数说明

参数名称 描述
opt.ret 接口onsuccess返回码。详细返回码请参考#4 返回码说明
opt.context 调用该接口时的context透传参数。
opt.groupname 调用本接口成功创建/绑定公会QQ群后,返回的群名字。

只有 opt.ret为0时,才会带有该参数。

opt.unionid 调用本接口进行绑定的公会QQ群的公会ID。

只有 opt.ret为0时,才会带有该参数。

opt.groupopenid 调用本接口成功绑定公会QQ群时返回的群openid,邀请、加入/退出时,都需要此参数。

只有 opt.ret为0时,才会带有该参数。


4. 回调示例

onSuccess: function(opt) {
      if( 0 == opt.ret ) { //成功回调里面,并且ret为0
        alert("QQ群操作成功: " + fusion.JSON.stringify(opt));
        alert("群名字:" + opt.groupname);
        alert("公会ID:" + opt.unionid);
        alert("群openid:" + opt.groupopenid);
       } 
      else {
          //成功回调里面,ret不为0,处理请求失败逻辑
       }
  }

3.2 邀请成员加入公会QQ群

1. 参数说明

参数名称 是否必须 类型 描述
type 必须 string 参数描述:操作类型。

邀请成员加入公会QQ群,传入的值为“invite”。

msg string 参数描述:邀请的内容。

文本显示位置:用户发送邀请后,会在邀请者接收到的邀请加入群的QQtips中显示。

receiver 必须 string 参数描述:表示被邀请成员的openid列表(这里传的openid对应的成员与当前发出邀请的用户不一定是好友关系)。

多个openid之间用“,”分隔,请使用数组的格式。
建议传入的openid不超过50个,如果多于50个,截取前面50个。

unionid 必须 string 参数描述:游戏公会ID。
groupopenid 必须 string 参数描述:群openid,在创建或绑定公会QQ群时获得。
zoneid number 支付营销分区配置说明页面,配置的分区ID即为这里的“zoneid”。

如果应用不分区,则为0。

context string 参数描述:透传参数,用于onSuccess和onCancel回调,以识别请求。

透传方式:调用本接口时传入该参数,onSuccess或onCancel回调时,在JS中使用opt.context即可获取该透传参数(opt为本接口的回调函数形参)。
例如用户操作成功后,会回调onSuccess时获取该参数的值:

onSuccess : function (opt) 
  {       
      alert("Succeeded: " + opt.context);  
  }
onSuccess 参数描述:用户操作成功后的回调方法。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击弹出框中的“确定”按钮,提示成功,弹出框关闭。

onError 参数描述:用户操作失败后的回调方法。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击弹出框中的“确定”按钮,但请求后台失败。失败的返回码详见#4 返回码说明

onCancel 参数描述:用户取消操作后的回调方法。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击取消或弹出框右上角的×按钮,弹出框关闭。用户取消时将同时关闭对话框,因此将先触发onCancel回调再触发onClose回调。

onClose 参数描述:对话框关闭时的回调方法。主要用于对话框关闭后进行UI方面的调整,onSuccess和onCancel则用于应用逻辑的处理,避免过度耦合。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击取消或弹出框右上角的×按钮,弹出框关闭。用户取消时将同时关闭对话框,因此将先触发onCancel回调再触发onClose回调。


2. 调用示例

fusion2.dialog.manageQQGroup({
     type: "invite",


     msg: "快来加入游戏公会吧",


     receiver: ["0000000000000000000000006C9BA44E", "0000000000000000000000006DD04B31"],


     unionid: "123456789",


     groupopenid: "5A4FDE2B0B9337747517014C753E745C",


     zoneid: "123",


     context: "manage-QQGroup-12345",


     onSuccess: function(opt) {
            alert("QQ群操作成功: " + fusion.JSON.stringify(opt));
     },


     onError: function(opt) {
            alert("QQ群操作失败: " + fusion.JSON.stringify(opt));
     },


     onCancel: function(opt) {
            alert("用户取消: " + fusion.JSON.stringify(opt));
     },


     onClose: function(opt) {
            alert("浮层关闭: " + fusion.JSON.stringify(opt));
     }
});


3. 返回参数说明

参数名称 描述
opt.ret 接口onsuccess返回码。详细返回码请参考#4 返回码说明
opt.context 调用该接口时的context透传参数。


4. 回调示例

onSuccess: function(opt) {
      if( 0 == opt.ret ) { //成功回调里面,并且ret为0
        alert("QQ群操作成功: " + fusion.JSON.stringify(opt));
       } 
      else {
          //成功回调里面,ret不为0,处理请求失败逻辑
       }
  }


3.3 加入公会QQ群

1. 参数说明

参数名称 是否必须 类型 描述
type 必须 string 参数描述:操作类型。

加入公会QQ群,传入的值为“join”。

name string 参数描述:加入公会QQ群时设置的群名片。

长度限制:控制在7个汉字以内,超过7个汉字进行截断。

unionid 必须 string 参数描述:游戏公会ID。
groupopenid 必须 string 参数描述:群openid,在创建或绑定公会QQ群时获得。
zoneid number 支付营销分区配置说明页面,配置的分区ID即为这里的“zoneid”。

如果应用不分区,则为0。

context string 参数描述:透传参数,用于onSuccess和onCancel回调,以识别请求。

透传方式:调用本接口时传入该参数,onSuccess或onCancel回调时,在JS中使用opt.context即可获取该透传参数(opt为本接口的回调函数形参)。
例如用户操作成功后,会回调onSuccess时获取该参数的值:

onSuccess : function (opt) 
  {       
      alert("Succeeded: " + opt.context);  
  }
onSuccess 参数描述:用户操作成功后的回调方法。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击弹出框中的“确定”按钮,提示成功,弹出框关闭。

onError 参数描述:用户操作失败后的回调方法。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击弹出框中的“确定”按钮,但请求后台失败。失败的返回码详见#4 返回码说明

onCancel 参数描述:用户取消操作后的回调方法。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击取消或弹出框右上角的×按钮,弹出框关闭。用户取消时将同时关闭对话框,因此将先触发onCancel回调再触发onClose回调。

onClose 参数描述:对话框关闭时的回调方法。主要用于对话框关闭后进行UI方面的调整,onSuccess和onCancel则用于应用逻辑的处理,避免过度耦合。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击取消或弹出框右上角的×按钮,弹出框关闭。用户取消时将同时关闭对话框,因此将先触发onCancel回调再触发onClose回调。


2. 调用示例

fusion2.dialog.manageQQGroup({
     type: "join",


     name: "tom",


     unionid: "123456789",


     groupopenid: "5A4FDE2B0B9337747517014C753E745C",


     zoneid: "123",


     context: "manage-QQGroup-12345",


     onSuccess: function(opt) {
            alert("QQ群操作成功: " + fusion.JSON.stringify(opt));
     },  


     onError: function(opt) {
            alert("QQ群操作失败: " + fusion.JSON.stringify(opt));
     },


     onCancel: function(opt) {
            alert("用户取消: " + fusion.JSON.stringify(opt));
     },


     onClose: function(opt) {
            alert("浮层关闭: " + fusion.JSON.stringify(opt));
     }
});


3. 返回参数说明

参数名称 描述
opt.ret 接口onsuccess返回码。详细返回码请参考#4 返回码说明
opt.context 调用该接口时的context透传参数。


4. 回调示例

onSuccess: function(opt) {
      if( 0 == opt.ret ) { //成功回调里面,并且ret为0或ret为11
        alert("QQ群操作成功: " + fusion.JSON.stringify(opt));
       } 
      else {
          //成功回调里面,ret不为0,处理请求失败逻辑
       }
  }


3.4 退出公会QQ群

1. 参数说明

参数名称 是否必须 类型 描述
type 必须 string 参数描述:操作类型。

退出公会QQ群,传入的值为“quit”。

unionid 必须 string 参数描述:游戏公会ID。
groupopenid 必须 string 参数描述:群openid,在创建或绑定公会QQ群时获得。
zoneid number 支付营销分区配置说明页面,配置的分区ID即为这里的“zoneid”。

如果应用不分区,则为0。

context string 参数描述:透传参数,用于onSuccess和onCancel回调,以识别请求。

透传方式:调用本接口时传入该参数,onSuccess或onCancel回调时,在JS中使用opt.context即可获取该透传参数(opt为本接口的回调函数形参)。
例如用户操作成功后,会回调onSuccess时获取该参数的值:

onSuccess : function (opt) 
  {       
      alert("Succeeded: " + opt.context);  
  }
onSuccess 参数描述:用户操作成功后的回调方法。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击弹出框中的“确定”按钮,提示成功,弹出框关闭。

onError 参数描述:用户操作失败后的回调方法。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击弹出框中的“确定”按钮,但请求后台失败。失败的返回码详见#4 返回码说明

onCancel 参数描述:用户取消操作后的回调方法。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击取消或弹出框右上角的×按钮,弹出框关闭。用户取消时将同时关闭对话框,因此将先触发onCancel回调再触发onClose回调。

onClose 参数描述:对话框关闭时的回调方法。主要用于对话框关闭后进行UI方面的调整,onSuccess和onCancel则用于应用逻辑的处理,避免过度耦合。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击取消或弹出框右上角的×按钮,弹出框关闭。用户取消时将同时关闭对话框,因此将先触发onCancel回调再触发onClose回调。


2. 调用示例

fusion2.dialog.manageQQGroup({
     type: "quit",


     unionid: "123456789",


     groupopenid: "5A4FDE2B0B9337747517014C753E745C",


     zoneid: "123",


     context: "manage-QQGroup-12345",


     onSuccess: function(opt) {
            alert("QQ群操作成功: " + fusion.JSON.stringify(opt));
     },


     onError: function(opt) {
            alert("QQ群操作失败: " + fusion.JSON.stringify(opt));
     },


     onCancel: function(opt) {
            alert("用户取消: " + fusion.JSON.stringify(opt));
     },


     onClose: function(opt) {
            alert("浮层关闭: " + fusion.JSON.stringify(opt));
     }
});


3. 返回参数说明

参数名称 描述
opt.ret 接口onsuccess返回码。详细返回码请参考#4 返回码说明
opt.context 调用该接口时的context透传参数。


4. 回调示例

onSuccess: function(opt) {
      if( 0 == opt.ret ) { //成功回调里面,并且ret为0
        alert("QQ群操作成功: " + fusion.JSON.stringify(opt));
       } 
      else {
          //成功回调里面,ret不为0,处理请求失败逻辑
       }
  }


4 返回码说明

返回码 含义说明
-1 转换群openid失败。
-2 解析用户openid失败。
-7 权限不足。如果用户不是公会QQ群的群主/管理员,进行邀请操作会返回该错误码。
-9 用户不在该公会QQ群内。
-10 公会ID和groupopenid的对应关系错误。
1 创建公会QQ群时,一个公会ID只能和一个QQ群进行绑定。
11 用户加入公会QQ群时,如果公会QQ群需要群主/管理员进行验证审核,此时的返回码为11。
12 用户要加入的公会QQ群不存在。
21 用户退出的公会QQ群不存在。
31 邀请加入的公会QQ群不存在。

FAQ

详见:FusionAPI调用相关问题

相关文档

修改QQ群成员的群名片:v3/qqgroup/set_namecard
同步公会聊天内容到对应的QQ群:v3/qqgroup/send_msg
查询公会QQ群的openid:v3/qqgroup/get_group_openid
查询用户所加入的公会QQ群信息:v3/qqgroup/is_group_member
获取用户所在公会QQ群的群成员信息:v3/qqgroup/get_app_groupmembers
解绑公会ID与QQ群:v3/qqgroup/unbind_qqgroup

以上信息是否解决您的问题?

Copyright © 1998 - 2017 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部