fusion2.dialog.brag

调用本接口不需要再申请权限,接口调用限制使用统一规则,请参阅:社交渠道使用优化指引

目录

What's New

2013年07月09日起,炫耀或挑战feeds的标题修改为应用名称,用户可从feeds中直观得知分享来自哪个应用,开发者无须做任何修改。
2013年03月15日起,调用本接口不需要再申请权限。
2013年01月24日起,接口调用限制使用了统一规则,请参阅:社交渠道使用优化指引
2012年9月17日起,新增挑战好友的授权模式弹框,支持传入参数“isfric”来决定挑战好友的弹框模式。关于挑战好友弹框模式详见下文参数说明中“isfric”的描述。
2012年9月12日起,支持发送分享feeds,被邀请围观的好友以@好友的形式展现在分享feeds中。

1 功能说明

1. 接口类型:前端JS接口。
2. 接口功能:向好友炫耀成就、挑战好友、邀请好友围观,用于拉动用户活跃,提升应用的用户留存。
3. 功能描述:
(1)当用户在应用中取得一定的成就时,应用只需在应用的前端JS代码中调用本接口,让用户向被超过的好友进行炫耀/挑战。
(2)调用本接口后,出现炫耀/挑战弹出框,弹出框中包含了好友选择器,用户可以选择好友来围观。
(3)同时,在炫耀/挑战弹框中支持分享给用户全部好友。
(4)在弹框中显示了炫耀/挑战的内容,用户点击此内容区域后,可以更改此内容。
(5)用户点击弹出框中的炫耀/挑战按钮后,被炫耀或挑战的用户即可收到炫耀信息或挑战信息,从而刺激用户的攀比心理,吸引被炫耀/挑战用户进入应用。
(6)如果用户在炫耀/挑战弹框中选择了围观的好友,且勾选了“分享给我的全部好友”,被邀请围观的好友会在“与我相关”的页面看到邀请围观信息,所有好友都能够在好友动态中看到相关炫耀或挑战信息。
(7)支持开发者通过传入参数“isfric”选择不同的挑战好友的弹框模式。关于挑战好友弹框模式详见下文参数说明中“isfric”的描述。

4. 接口调用限制:
(1)权限:调用本接口前,请通过企业QQ联系商务支持申请接口权限。
(2)支持的平台:本接口目前仅支持QQ空间平台。
(3)调用的频率限制,请参阅:社交渠道使用优化指引
5. 特别备注:
(1)当用户PC端QQ状态为“我在线上”、“Q我吧”或“隐身”,才会收到QQtips。
(2)如果用户PC端QQ状态为“离线”,上线后也会收到QQtips。

2 场景说明

2.1 入口说明

游戏类应用中,当用户的等级、积分、金币、经验、成就、装备达到一定等级的时候,特别是超过他的好友的时候, 应用中弹出弹框,在弹框中设置类似“炫耀一下”或“下战书”的按钮,鼓励用户点击。

用户点击按钮后,会根据开发者调用接口时传入的参数弹出不同的弹框:
方案1:如果参数“type”传入的值为“brag”,弹出炫耀弹框;
方案2:如果参数“type”传入的值为“pk”,且参数“isfric”传入的值为“0”或不传,弹出正常模式弹框,即弹框中可以选择围观好友并分享给全部好友;
方案3:如果参数“type”传入的值为“pk”,且参数“isfric”传入的值为“1”,弹出授权模式弹框,即弹框中不需用户选择围观好友,确认后即可下战书。

2.2 发起调用以及弹框效果展示

用户在应用中取得成就后,应用调用本接口(接口调用详见下文第3节说明),弹出炫耀弹框或挑战弹框。

方案1和方案2:正常模式弹框
弹框中有如下元素:
(1)弹框中有应用传入的炫耀或挑战图片。建议该图片能够表现用户炫耀的场景,或两个用户PK的场景。
(2)弹框中有应用传入的分享feeds主题描述,用户看到该主题,即可知道分享feeds的目的。
(3)弹框中有关于向好友炫耀或向用户发起挑战的一句内容描述,用户可以修改此内容。
(4)弹框中有邀请好友围观的描述,描述下为好友选择器,用户可以选择围观的好友。
(5)弹框中有分享给好友的复选框,用户可以选择是否将炫耀或挑战信息分享给所有的好友(“炫耀”模式下默认选中,“挑战”模式下默认不选中)。
炫耀弹框如下图所示:
fusion2.dialog.bragging_1.png
挑战弹框如下图所示:
fusion2.dialog.bragging_2.png

方案3:授权模式弹框
弹框中有如下元素:
(1)弹框中有应用传入的挑战图片。建议该图片能够表现两个用户PK的场景。
(2)弹框中有关于向好友发起挑战的一句内容描述,用户可以修改此内容。
(3)弹框中有“给以上好友发送时不再询问”的复选框,用户勾选后,如果下次挑战对象全部和这次相同,则可以直接发送挑战,不用再弹出确认框。
授权模式挑战弹框如下图所示:
fusion2.dialog.bragging_16.png

2.3 结果展现

发送成功后,好友可通过如下多种方式收到相关信息:
1. QQtips
好友可以通过QQtips接收到炫耀/挑战/邀请围观消息,以提升用户的活跃度。
炫耀消息示例如下:
fusion2.dialog.bragging_3.png
挑战消息示例如下:
fusion2.dialog.bragging_4.png
邀请围观炫耀消息示例如下:
fusion2.dialog.bragging_10.png
邀请围观挑战消息示例如下:
fusion2.dialog.bragging_11.png

2. 应用助手
被挑战/炫耀,以及被邀请围观的好友,在应用中心的应用助手页可以接收到相应的消息,且挑战、炫耀、围观分为三类显示,以提升用户的活跃度。
炫耀消息示例如下:
fusion2.dialog.bragging_5.png
挑战消息示例如下:
fusion2.dialog.bragging_6.png

3. 应用动态
炫耀消息:
应用中心的应用动态显示被动点对点消息,如“XXX在XXX中超越了你,赶紧来看看!”;同时会显示主动点对多消息,如“XXX在XXX中击败了XXX”。
应用内页的应用动态只显示主动点对多消息,如“XXX在XXX中击败了XXX”。

挑战消息:
应用中心的应用动态显示被动点对点消息,如“XXX在XXX中中向你下了战书,马上应战!”;同时会显示主动点对多消息,如“XXX在XXX中向XXX发了战书。”。
应用内页的应用动态只显示主动点对多消息,如“XXX在XXX中向XXX发了战书。”。

4. 系统消息
用户向好友炫耀/挑战后,在好友个人中心的系统消息中也会收到炫耀/挑战信息,示例如下:
fusion2.dialog.bragging_8.png

5. 个人中心
如果在炫耀弹框中有围观的好友,且勾选了“分享给我的全部好友”,被邀请围观的好友在个人中心会收到分享feeds,且被邀请围观的好友以@好友的形式展现在分享feeds中。
炫耀feeds示例如下:
fusion2.dialog.bragging_12.png
挑战feeds示例如下:
fusion2.dialog.bragging_13.png

如果用户在弹框中勾选“分享给我的全部好友”,该用户的所有好友会在个人中心收到分享feeds。
炫耀feeds示例如下:
fusion2.dialog.bragging_14.png
挑战feeds示例如下:
fusion2.dialog.bragging_15.png

3 接口调用说明

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

3.1 参数说明

参数名称 是否必须 类型 描述
type 必须 string 参数描述:标识弹框的类型,只能传入“brag”或“pk”。

“brag”:表示弹出炫耀弹框,弹框标题为“向好友炫耀”;
“pk”:表示弹出挑战弹框,弹框标题为“下战书”。

msg 必须 string 参数描述:弹框中的内容描述,建议语言生动、有足够的炫耀、挑战的意味,能够吸引用户。

长度限制:控制在50个汉字(100个字符)以内。
文本显示位置:图片右侧的炫耀或挑战内容区域,见上文2.2节弹框图片中的标注3。

receiver 必须 string 参数描述:被炫耀/挑战的对象的openid。开发商可通过v3/relation/get_app_friends接口获取玩家所有已安装的好友的openid,并在挑战/炫耀时传入对应玩家的openid即可

限制:最多传入1个openid,且只能传入已安装好友的openid。

img 必须 string 参数描述:弹框中炫耀/挑战场景图的URL。建议该图片能够表现用户炫耀的场景,或两个用户PK的场景,对用户有强烈的吸引力。

图片显示位置:见上文2.2节弹框图片中的标注1。
图片文件大小:无要求。
图片格式:.jpg, .png, .jpeg。
图片规格:120×120px。
是否自动缩放:是。超过120×120px,会按比例进行缩放。
图片URL域名限制:
hosting应用要求将图片存放在APP域名下或腾讯CDN。
non-hosting应用要求将图片上传到该应用开发者QQ号对应的QQ空间相册中。即non-hosting应用图片域名必须为:qq.com、pengyou.com、qzoneapp.com、qqopenapp.com、tqapp.cn。

isfric string 参数描述:标识挑战弹框的模式。仅当“type”的值为“pk”时,传入该参数。

0或不传:正常模式。即弹框中可以选择围观好友并分享给全部好友;
1:授权模式。即不需用户选择围观好友,如果用户勾选“给以上好友发送时不再询问”,表示用户进行了授权,下次挑战对象如果全部和这次相同,则可以直接发送挑战,不用再弹出确认框。

title string 参数描述:弹框中的分享feeds主题描述。

默认值:如果不传该参数值,炫耀feeds主题默认为“好友炫耀贴”,挑战feeds主题默认为“好友挑战书”。
长度限制:控制在16个汉字(32个字符)以内。
文本显示位置:图片右侧的feeds主题文字区域,见上文2.2节弹框图片中的标注2。

dsc string 参数描述:用户炫耀或挑战后,在feeds和QQ消息中显示的文字内容。该参数暂时作为保留字段。

长度限制:控制在35个汉字(70个字符)以内。
文本显示位置:发送给被炫耀或被挑战者的feeds和QQ消息。

crowd string 参数描述:开发者传入的围观对象的openid(可通过v3/relation/get_rcmd_friends接口获取平台推荐的好友),且传入的围观对象为最近7天登录过应用的用户。

格式限制:可传入多个openid,多个openid之间用“,”分隔,最多可传入3个openid,请使用数组的格式。
注:炫耀/挑战对象不能作为围观的对象,且需要为7天内登录过应用的活跃用户;
“isfric”的值为“1”时,不用传入该参数。

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

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

onSuccess : function (opt) 
  {       
      alert("Succeeded: " + opt.context);  
  }
source string 参数描述:透传参数,由开发者自定义该参数内容。

开发者可根据这个参数的内容,判断被炫耀/挑战的用户是点击哪个好友发送的信息。
例如:
用户A向C发送炫耀/挑战信息时,source的值为“openid=001”,用户B向C发送炫耀/挑战信息时,source的值为“openid=002”。当用户C点击信息链接进入应用时,url中会携带app_custom参数,如果app_custom的值为“openid=001”,说明C点击的信息是A发送的,如果app_custom的值为“openid=002”,说明C点击的信息是B发送的。

onSuccess 参数描述:用户操作成功后的回调方法。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击弹出框中的“炫耀一下”按钮或“下挑战书”按钮,提示成功,弹出框关闭。
可通过如下方式获取被炫耀/挑战用户的相关信息:
(1)被炫耀/挑战者的openids: opt.receiver
(2)被炫耀/挑战者的数量: opt.receiver.length
(3)被邀请围观者的openids: opt.crowd
(4)被邀请围观者的数量: opt.crowd.length

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

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

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

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

3.2 调用示例

fusion2.dialog.brag
({
     type : "brag", 


     title : "向好友炫耀一下",


     msg : "你弱爆啦!!被我在周赛排名中超越了,还赢了一大笔奖金!不服气的话来找我再战吧!", 


     receiver : ["00000000000000000000000000009FED","00000000000000000000000000009FED"],


     crowd : ["000000000000000000000000001C2DF9"],


     img : "http://appimg.qq.com/happyfarm/module/ui/icons/award2.png",	  


     context : "braging-12345", 


     source :  "a=b&c=d", 


     onSuccess : function (opt) 
     {  
        // 通过opt.context可获取接口中传入的context透传参数,以识别请求
        alert("Succeeded: " + opt.context); 
        window.console && console.log(opt);		 
     },


     onCancel : function (opt) 
     {  
        // 通过opt.context可获取接口中传入的context透传参数,以识别请求
        alert("Cancelled: " + opt.context);  
     },


     onClose : function (opt) 
     {  
        // 通过opt.context可获取接口中传入的context透传参数,以识别请求
        alert("Closed: " + opt.context);  
     }
  })


3.3 返回码说明

返回码 含义说明
1000 非法操作。
请从如下几个方面进行排查:

1、不是POST请求;
2、传入的platform不合法;
3、参数sendmsg,sharedesc超过长度;

1001 服务器繁忙,请稍候再试。

请从如下几方面进行排查:
1、获取应用信息失败;
2、获取关系链失败;
3、获取昵称失败;
4、获取“免打扰模式”接口失败;
5、验证是否有发送名额接口时出错;
6、发送请求或者失败;
7、批量uin换openid失败。

1002 请先登陆。
1005 参数错误。

请从如下几方面进行排查:
1、围观的接受者和围观者数量有误;
2、入参中,typeid不对。

1013 发送名额不足。
1025 接收者数量超过最大限制。


FAQ

详见:FusionAPI调用相关问题

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

Copyright © 1998 - 2018 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部