fusion2.dialog.inviteToGroup

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

目录

What's New?

2013年8月19日起,支持开发者传入官方QQ群的openid,在用户加入群时,会给用户优先展示这些官方群(详见参数说明中的"officialGroup")。

1 功能说明

1. 接口类型:前端JS接口。
2. 接口功能:引导用户加入应用已绑定的群,或用户自己创建群并与应用绑定。
3. 功能描述:
(1)要实现该功能,只需在应用的前端页面代码中调用本接口,并在应用的界面上放置类似“加入应用群”的按钮,或在用户要和好友互动时,调用本接口,引导用户加入群,和群好友进行互动。
(2)用户触发应用调用本接口时,弹出弹框,用户可加入已有的应用群,或创建新的应用群。
(3)用户加入群后,可直接在应用中给群好友发送请求/赠送礼物等,而无需添加为好友,从而促进应用中好友的互动,提升用户活跃度。

4. 接口调用限制:
支持的平台:本接口目前仅支持空间平台。

2 场景说明

2.1 入口说明

建议在以下场景调用接口,鼓励用户加入群:
(1)在应用界面上放置类似“加入应用群”按钮,方便用户在需要的时候能自主加群;
(2)当用户是第一次进入应用,弹窗鼓励用户加入应用群,帮助用户尽快熟悉应用,并能方便的与其他用户互动。

2.2 弹框效果展示

1. 应用调用本接口时,需要传入吸引用户加入群的文字和图片,这些文字和图片会在如下的弹框中展示; 在弹框中,用户可以加入群或创建新群。
fusion2.dialog.inviteToGroup_1.png

2. 用户点击“立即加入应用群”后,出现“加入群”页面,用户可以选择已有的应用群申请加入。
fusion2.dialog.inviteToGroup_2.png
注:1.为避免群人数太多造成骚扰,推荐群时会优先推荐尚不饱和(成员数未超过最大成员数的80%)的群
2.官方群仍然置顶推荐,不受这个80%阈值的影响

用户点击“创建新群”后,出现“创建群”页面,用户可以创建新的QQ群,或使用现有的QQ群与应用绑定。
fusion2.dialog.inviteToGroup_3.png


3. 用户加入应用群后,可以在发送好友请求/免费礼物时,直接发送给群中的好友,而无需添加其为好友。
fusion2.dialog.inviteToGroup_4.png


3 接口调用说明

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

3.1 参数说明

参数名称 是否必须 类型 描述
msg string 参数描述:推荐用户加入应用群的运营文字,请尽量简洁生动,能够吸引用户加入应用群。如果不传,则默认为“无需添加好友,就能与爱玩这款应用的朋友们一起互动!”。

长度限制:控制在50个汉字以内。
文本显示位置:见上文2.2节“应用互动群”弹框的引导文字。

img string 参数描述:推荐用户加入应用群的运营图片。如果不传,则显示默认图,见2.2节中的弹框中的图片。

图片显示位置:见上文2.2节“应用互动群”弹框的引导文字。
图片文件大小:无要求。
图片格式:.jpg, .png, .jpeg。
图片规格:482×140px。
是否自动缩放:是。但建议按照图片规格482×140px准备图片。

officialGroup string 参数描述:用户在加入群时,推荐给用户的应用群的openid列表。

格式限制:最多可输入5个群的openid,以逗号隔开。
注:为方便开发者拿到官方群的openid,我们在get_group_openid接口中增加了opt参数,opt默认为0时,使用老的功能(通过zoneid和unionid来换取groupopenid),opt为1时,实现通过appid和群号码(数字)换取groupopenid。推荐开发者使用opt为1的方式获取。

onSuccess 参数描述:用户操作成功后的回调方法。目前仅支持空间平台。

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

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

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

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

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

onError 参数描述:用户操作失败后的回调方法。目前仅支持空间平台。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击弹出框中的“申请加入”按钮,或“创建群”按钮,提示失败。

3.2 调用示例

fusion2.dialog.inviteToGroup

({

  msg : "快来加入应用群,与群好友互动",


  img : "http://qzonestyle.gtimg.cn/open_proj/proj_app_store_v2/ac/app/popup/bg_text_tip.png",


  officialGroup : "5A4FDE2B0B9337747517014C753E745C,5A4FDE2B0B9337747517014C753E745D",


  onSuccess : function (opt) { alert("发送成功: "+fusion.JSON.stringify(opt)); },


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


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


  onClose : function (opt) {   alert("发生错误: " +fusion.JSON.stringify(opt)); }

});

3.3 返回码说明

返回码 含义说明
-1 登录错误。
-2 服务器错误。
-3 参数错误。
-4 群openid转群号失败。
-5 群号转群openid失败。
-6 openid转化uin失败。
-7 群角色无效。
-8 HTTP method无效,请用post。
-9 不在群上。
-10 检查appid或公会id错误。
其他 系统错误。

FAQ

详见:FusionAPI调用相关问题

相关文档

查询用户所加入的应用QQ群信息:v3/qqgroup/is_group_member
获取用户所在应用QQ群的群成员信息:v3/qqgroup/get_app_groupmembers

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

Copyright © 1998 - 2018 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部