fusion2.dialog.sendRequest

目录

What's New?

2013年09月11日起,sendRequest接口支持将好友请求/免费礼物发送给群好友。开发者在传入receiver时需同时传入群openid,以方便验证群好友的有效性。(详见接口调用说明中的opengid参数)

2013年01月24日起,接口调用限制使用了统一规则,请参阅:社交渠道使用优化指引

2013年01月10日起,1个用户在1个应用里,1次最多能给3个好友赠送礼物或发送请求;参数“receiver”最多可传入的openid的个数将由10个调整为1个。
后续该数值将根据各应用的请求转化率(用户进入应用次数/请求发送次数),由系统自动调整。请开发者及时优化应用内赠送礼物/发送请求的相关功能,以提升请求转化率。

1 功能说明

本接口是前端JS接口:
(1)一种用于应用推广的前端接口;
(2)适用于freegift和request两种场景。应用调用本接口后,用户可在该应用内向好友赠送礼物或者发送请求;
(3)发送后将以消息的形式在好友的应用页、应用中心的应用助手页得展现,从而获得高流量的曝光。
(4)目标用户可收到QQtips提示,点击QQTips可看到礼品卡(应用达标才可申请,申请规则及方式详见这里);
(5)目标用户在个人中心可看到被赠送礼物的feeds(应用达标才可申请,申请规则及方式详见这里)。
(6)为避免对用户过度骚扰,每个用户每天最多收到的应用礼物QQTIPS以及feeds有一个上限。

2 使用freegift和request的好处

(1)极大提升应用曝光率:在应用使用页、应用中心应用助手页曝光。
(2)提高应用注册量:利用Qzone,朋友平台成熟的关系链,强social的方式,用户非常容易接受应用从而成为该应用的玩家。
(3)提高应用用户活跃度:通过请求或礼物,用户之间互动的渠道增加,提升用户活跃度。

3 接口调用限制

(1)本接口目前支持空间平台和朋友平台。该接口的联调涉及到请求的发送,接受和处理,目前空间平台和朋友平台提供了应用助手进行联调,即使其他平台上调用了该接口无法看到联调效果。
(2)接口调用限制请参阅:社交渠道使用优化指引

4 场景说明

支持以下四种场景:
1. freegift(用户自己指定好友):应用未指定好友,用户需要自己在好友选择器中选择好友(包括未安装应用的好友),并赠送礼物。

2. freegift(应用指定好友):应用指定好友并赠送礼物。
由于需要在参数中传递已安装了应用的好友的OpenID,因此non-hosting应用不能使用该场景。
赠送礼物时,会弹出授权确认框,请用户确认:
(1)仅能对好友赠送礼物。非好友会自动过滤,不会收到相关消息。
(2)如果指定的目标对象所有都获得过用户授权,则不会弹出确认框,直接赠送礼物,发送成功后不会有提示。
(3)如果发送对象中包含有未授权对象,仍然会弹出确认框,让用户确认是否赠送礼物,发送成功后会有提示。

3. request(用户自己指定好友):应用未指定好友,用户需要自己在好友选择器中选择已安装应用的好友,并发送请求。

4. request(应用指定好友):应用指定好友并发送请求。
在参数中传递已安装了应用的好友的OpenID,因此non-hosting应用不能使用该场景。
发送请求时,会弹出授权确认框,用户确认发送后,才发送请求:
(1)仅能对好友发送request。非好友会自动过滤,不会收到请求。
(2)如果指定的目标对象所有都获得过用户授权,则不会弹出确认框,直接发送请求,请求发送成功后不会有提示。
(3)如果发送对象中包含有未授权对象,仍然会弹出确认框,让用户确认是否发送请求,请求发送成功后会有提示。

5 效果演示

5.1 freegift(用户自己指定好友)

下面的案例演示了freegift(用户自己指定好友)场景下,用户在弹出层的好友选择器中选择对象,进行礼物赠送的过程。

Step1:用户选择礼物
应用中可以设置一个礼物赠送区,或者在应用的商城内可以进行赠送的物品旁设置”赠送“按钮。
礼物可以是应用内的道具或者其他社交类物品。如下图所示:
freegift_1.png

Step2:用户选择要赠送礼物的好友
用户选中某一个礼物后,即会弹出好友选择框,用户可以在该框中选订赠送礼物的对象。好友选择框样式如下:
fusion2.dialog.sendrequest_1.png

Step3:赠送成功后,好友可收到QQtips,在个人中心看到礼物feeds,在应用使用页以及应用中心的应用助手页收到消息
(1)好友可收到QQ客户端的tips 提示,如下图所示:
联调时请注意: 为避免对用户过度骚扰,每个用户每天最多收到的应用礼物QQTIPS有一个上限。
fusion2.dialog.sendrequest_3.png

目标用户点击QQtips,即可打开礼品卡弹框:
-可以点击“领取礼物”按钮,领取道具/物品;
-可点击应用名称链接进入应用;
-可以点击“答谢”按钮进行答谢或礼物回赠。但是注意由于该用户可能还没有安装应用,因此只能回赠平台(QQ空间)提供的礼物。
fusion2.dialog.sendrequest_4.png
(2)好友在自己的个人中心可以看到被别人赠送礼物的feeds,如下图所示:
联调时请注意: 为避免对用户过度骚扰,每个用户每天最多收到的应用礼物feeds有一个上限。
fusion2.dialog.sendrequest_5.png

(3)好友在应用使用页收到消息,见下图右侧红框标识处(下图是QQ空间的应用使用页面):
freegift_2.png
(4)好友在应用中心的应用助手页收到消息,见下图红框标识处:
- QQ空间:进入应用中心后,可以在左上角看到“应用助手”链接,点击即进入应用助手
freegift_3.png

- 腾讯朋友平台:在首页右上角可看到消息盒子,点击即进入“系统告知”页面,其中的“应用消息”里放置所有应用相关的消息:
freegift_5.png freegift_6.png

Step4:点击接收后,在应用内的信息中心页面上处理该消息
好友点击“接收礼物”按钮,即进入应用内的信息中心,去处理该消息,见下图红框标识处:
(目前平台并没有为应用提供统一的信息中心,即应用需要自己提供消息中心,以处理请求。信息中心是必须的,否则用户收到请求/送礼的消息后无法进行互动。)
freegift_4.png

5.2 freegift(应用指定目标对象)

(1)用户触发“赠送礼物”动作后,赠送礼物前需要用户授权确认。
确认框示意图如下:
fusion2.dialog.sendrequest_6.png

(2)赠送礼物成功后,被赠送礼物的好友可收到QQtips,在个人中心看到礼物feeds,在应用使用页以及应用中心的应用助手页收到消息。这些与上面5.1节的表现是一样的。
(3)好友点击“接收礼物”按钮,即进入应用内的信息中心,去处理该消息。

5.3 request(应用指定目标对象)

下面的案例演示了request(应用指定目标对象)场景下,应用传入指定的目标发送对象,用户在弹出框中确认,然后发送请求的过程。
注意:
(1)仅能对当前用户的好友发送request。非好友会自动过滤,不会收到请求。
(2)如果指定的目标对象所有都获得过用户授权,则不会弹出确认框,直接发送请求,请求发送成功后不会有提示。
(3)如果发送对象中包含有未授权对象,仍然会弹出确认框,让用户确认是否发送请求,请求发送成功后会有提示。
(4)应用传入指定的目标对象只能为1个。
(5)发送请求的动作一定必须是用户自己触发的。腾讯后台将对接口调用次数进行监控,对于异常数据进行核实,如果未经用户触发私自调用赠送礼物接口,将永久封锁应用调用该接口的权限。

Step1:用户触发“发送请求”动作
用户在应用使用过程中触发了“发送请求”动作。如下图所示:
request_1.png

Step2: 用户确认发送请求
这一步是为了取得用户授权。
用户需要在弹出框中点击“发送”按钮,确认发送请求。
如果勾选了弹出框左下侧的“给以上好友发送时不再询问”,则后续不会再出现该确认框。但如果发送对象中包含有未授权对象,则仍然会弹出确认框。如下图所示:
request_5.png
注意应用在这里只能传入1个目标对象。

Step3:用户安装了该应用的好友在应用使用页和应用中心的应用助手页收到消息
(1)用户安装了该应用的好友在应用使用页收到消息,见下图右侧红框标识处:
request_2.png
(2)好友在应用中心的应用助手页收到消息,见下图红框标识处:
- Qzone平台:进入应用中心后,可以在左上角看到“应用助手”链接,点击即进入应用助手
freegift_3.png

- 腾讯朋友平台:在首页右上角可看到消息盒子,点击即进入“系统告知”页面,其中的“应用消息”里放置所有应用相关的消息:
freegift_5.png freegift_6.png

Step4:点击接收后,在应用内的信息中心页面上处理该消息
好友点击“处理请求”按钮,即进入应用内的信息中心,去处理该消息,见下图红框标识处:
(平台并没有为应用提供统一的信息中心,即应用需要自己提供消息中心,以处理请求。信息中心是必须的,否则用户之间无法进行互动。)
request_4.png

5.4 request(用户自己指定好友)

(1)用户触发“发送请求”动作后,用户在弹出层的好友选择器中选择对象,发送请求。
发送请求的好友选择器示意图如下:
-空间平台,弹框左侧的好友列表中给出了已安装应用的好友,还支持“推荐好友”(推荐好友是指通过平台计算,给出的近期活跃该应用的好友,用户给该类好友发request获得的响应比自己选择好友要高):
fusion2.dialog.sendrequest_8.png
-朋友平台,弹框左侧的好友列表中只有已安装应用的好友,不支持“推荐好友”(本接口中推荐好友是指尚未安装应用,但是平台根据推荐算法计算出来的有可能安装应用的好友):
fusion2.dialog.sendrequest_7.png
(2)好友在应用使用页和应用中心的应用助手页收到消息,这些与上面5.3节是一样的。
(3)好友点击“处理请求”按钮,即进入应用内的信息中心,去处理该消息。

6 接口调用说明

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

6.1 参数说明

参数名称 是否必须 类型 描述
type 必须 string 调用类型,这里可传入request或freegift。
receiver string数组 表示接收者OpenID,只能传1个接收者的OpenID。

-如果想使用“应用指定目标对象”模式(不弹出好友选择框),则这里的参数值里必须传入已安装了应用的好友的OpenID(可通过v3/relation/get_rcmd_friends接口获取平台推荐的好友)。如果传多个OpenID,只取第1个进行验证后显示。
-如果想使用“用户自己指定好友”模式(弹出好友选择框),这里也必须传该参数,参数值为空值(receiver : [""])。
non-hosting应用由于不能调用好友关系链接口来获取OpenID,只能使用“用户自己指定好友”模式,则这里必须传值空值,前台表现为弹出好友选择框让用户自行选择好友。

title 必须 string 免费礼物的名称 。

请控制在6个字以内
注意:在freegift场景下,该名称将出现在礼品卡上 ,如果超过6个汉字,则礼品卡上的礼物名称处第6个汉字后面为省略号。

msg 必须 string 送礼或请求的默认赠言,请控制在35个汉字以内。可由用户修改,默认赠言请尽量简洁生动。

赠言显示逻辑:优先展示应用传入的默认赠言,其次显示系统默认赠言。系统默认赠言从下面几条中随机选择:
1. 我在玩游戏的时候想到了你,送你一份礼物,如果你喜欢,就跟我一起来玩吧~
2. 有太多的欢乐想与你分享,有太多的心事想向你倾诉:亲,今天玩应用了吗?
3. 发现一个特别有意思的应用,现在正式推荐给你,快点击领取礼物,我那里等着你!
4. 我能想到最快乐的事,就是和你一起玩游戏!
5. 工作辛苦有木有?不如一起打怪兽!送你一份小礼物,希望与你并肩作战!
6. 偶尔也想逃离现实,在虚拟的世界透透气。我享受玩游戏时的轻松自在,你也一起来吧 :)。
7.辛苦的工作的同时也要偶尔休闲一下,送一份小礼物你,和我一起来放松放松吧~
8.偶正在这里辛苦的奋斗着,和你一起分享偶滴成果~赶快领取礼物吧~

img 必须 string 图片的URL,建议为应用的图标或者与请求相关的主题图片,规格为65*65 px。

hosting应用要求将图片存放在APP域名下或腾讯CDN。
non-hosting应用要求将图片上传到该应用开发者QQ号对应的QQ空间相册中。即non-hosting应用图片域名必须为:qq.com、pengyou.com、qzoneapp.com、qqopenapp.com、tqapp.cn。

desc string request的内容或freegift的物品描述。
opengid string数组 标识用户所在QQ群的openid,如果有多个openid,请使用逗号隔开。开发者可以在拉取用户所属群的时候获取群的openid。
access string 标识当次的免费礼物信息可以通过哪些渠道发送给好友。

该参数仅支持QQ空间平台的应用,且仅当“type”=freegift时才有效。
0:使用默认的平台触达方式,即应用助手、好友应用动态、应用内页动态等,不通过被动feed和礼品卡发送。
1:除使用默认触达方式外,当次选择的好友增加礼品卡触达方式,直至礼品卡用量消耗完(礼品卡使用次数详见黄钻礼品卡使用规则)。
2:除使用默认触达方式外,当次选择的好友增加被动feed触达方式,直至被动feed用量消耗完(被动feed使用次数详见被动feed使用规则)。
3:除使用默认触达方式外,平台智能选取礼品卡和被动feed触达,直至用量消耗完。
:礼品卡和被动feed渠道剩余量可通过发送成功后的回调参数“monfeed”、“dayfeed”、“moncard”、“daycard”获得。
默认值:
对于QQ空间平台,默认取值为3;
对于其他平台,默认取值为0。

exclude string 在用户自己指定好友的场景中,如果开发者不希望某些用户显示在好友选择器中,可传入这些用户的openid,多个openid之间用“,”分隔(“exclude”和“specified”一共最多可传入50个openid),好友选择器则不显示这些openid对应的用户。
specified string 在用户自己指定好友的场景中,如果开发者需要在好友选择器中显示指定的用户,可传入这些用户的openid,多个openid之间用“,”分隔(“exclude”和“specified”一共最多可传入50个openid),好友选择器会显示这些openid对应的用户。
only string 仅当设置了“specified”,需要传入该参数,用于标识是否在好友选择器中只显示“specified”指定的用户。默认值为0。

0:显示“specified”指定的用户,同时显示好友列表和已安装好友。
1:只显示“specified”指定的用户,无好友列表和已安装好友。此时必须保证“specified”有可用的openid传入,否则会报错。

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的请求。

context string 透传参数,用于onSuccess和onCancel回调时传入的参数,以识别请求。
callback string 请传入处理某一条请求时的回调URL。

callback的使用场景:用户点击QQ空间“应用助手”中该应用后的“现在就去处理”按钮,进入平台为应用提供的信息中心,然后点击某一条请求后的“接受”或“取消”按钮,即回调该URL,进行具体的请求处理。
由于目前平台并没有为应用提供统一的信息中心,应用需自己开发信息中心,因此目前传入的回调URL并不起作用。

onSuccess 发送成功后的回调。例如可以使用如下语句:

flash.sendGiftSuccess(opt.context, opt.receiver,opt.receiver.length, opt.msg, opt.monfeed, opt.dayfeed, opt.moncard, opt.daycard);
opt结构体的方法说明:
opt.context:调用该接口时的context透传参数。
opt.receiver:为接收者OpenID数组。
opt.receiver.length:接收者的个数。
opt.msg:为用户填写的赠言。
opt.monfeed:被动feed渠道月剩余量。
opt.dayfeed:被动feed渠道当天剩余量。
opt.moncard:礼品卡渠道月剩余量。
opt.daycard:礼品卡渠道当天剩余量。
:opt.monfeed、opt.dayfeed、opt.moncard、opt.daycard仅当应用接入QQ空间平台,且“type”=freegift时才返回。

onCancel 用户取消发送时的回调方法。

用户取消发送时将同时关闭对话框,因此将先触发onCancel回调再触发onClose回调,opt.context为调用该接口时的context透传参数。

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

6.2 调用示例

fusion2.dialog.sendRequest

({

type : 'freegift',


receiver : [""],


title : '扩地证',


msg : '送你一个扩地证,赶快扩大城市面积吧!',


img:'http://app24341.qzoneapp.com/app24341/feed_clown.png',


source :"ref=freegift&zoneid=2",


desc : '用于扩大土地面积',


context : '1315885899: 86933d85682a0bbc318616d90fa641bb',


callback : 'http://app24341.qzoneapp.com/receive_request?id=12345',


onSuccess : function (opt)

{

  //opt.context : '1315885819: 86933d85682a0bbc318616d90fa641bb'
  //opt.receiver : '00000000000000000000000000009FED'      
  //opt.receiver.length : 1       
  //opt.msg : '老婆送你个扩地证~'
  //opt.monfeed : 999
  //opt.dayfeed : 99
  //opt.moncard : 999
  //opt.daycard : 99
  //flash.sendGiftSuccess(opt.context, opt.receiver, opt.receiver.length, opt.msg, opt.monfeed,  opt.dayfeed, 
  //                     opt.moncard, opt.daycard);

},


onCancel : function (opt) { },


onClose : function (opt) { }

});

6.3 返回码说明

返回码 含义说明
1000 非法操作。可能原因如下:

1、调用CGI不使用POST方式。
2、入参中,uin pfid appid为空;
3、pfid传入不合法。

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

请按照如下几方面进行排查:
1. 判断是否安装这款应用失败;
2. 获取应用信息失败;
3. openid转uin接口失败;
4. 获取“免打扰模式”接口失败;
5. 验证是否有发送名额接口时出错;
6. 发送请求或者失败。

1002 请先登录。

用户没有登录态。

1005 参数错误。

uins、openids、unions传空,或typeid传错。

1011 您还没有安装该应用。
1013 发送名额不足。

每个用户可发送请求的次数是有限的,如果超过限制,会提示名额不足。

1014 只能对好友进行操作。
1015 已送过礼物。
1030 您的请求过于频繁,请稍后再尝试。
1212 有部分好友没有被授权自动发送,请提示用户授权。



6.4 接口使用优化指南

为了充分发挥Request/Freegift功能,进一步增强用户间的互动,提升应用的活跃度,建议您在以下三个环节进行优化:
1. 发起:通过各种方法为用户推荐近期在应用中活跃的好友,用户在这些好友中选择发送Request/Freegift请求,提升好友响应率。
2. 接收:通过多种渠道让好友能够接收到请求feeds。
3. 回流:好友通过请求feeds进入应用时,自动弹出请求处理弹框,方便用户操作。
详细信息如下图所示:
sendrequest_1.png

7 联调说明

Step1:发起请求,注意需要写2份数据

应用侧在应用内部调用FusionAPI,发起请求/赠送操作。
注意:
本期版本中,平台没有为应用提供统一的信息中心,所以应用需要写2份数据,一份请求发给平台的FusionAPI,同时保存一份用于在应用自己的信息中心中展示。

Step2:进入“应用助手”

(1)进入QQ空间应用助手:
request的接收者登录QQ空间以后,点击应用中心左上角的“应用助手”即进入应用助手页面,如下图所示:
fusion2.assistant.png

应用助手中,同一个应用的消息是聚合展示的。在页面中找到该应用的消息描述(例如:xxx等x人送了您x份免费礼物), 如下图所示:
fusion2.dialog.sendrequest_2.png

(2)进入腾讯朋友应用助手:
request的接收者登录腾讯朋友以后,在首页右上角可看到消息盒子,消息盒子会有应用消息的查看链接,如下图所示:
freegift_5.png
点击即进入“系统告知”页面,其中的“应用消息”里放置所有应用相关的消息,如下图所示:
freegift_6.png

Step3:点击该应用的“去处理请求”按钮,跳转到应用页面

用户点击应用助手中的“去处理请求”按钮,会跳转到应用页面,并在跳转URL中透传参数:
(1)免费礼物,则透传参数为:&actiontype=freegift。

(2)应用请求,则透传参数为:&actiontype=request。

Step4:进入应用信息中心处理单条请求

应用需打开信息中心,跳转URL中带有来源信息&source=appassistant_request。用户可以在信息中心中进行单条请求的处理。

平台并没有为应用提供统一的信息中心,即应用需要自己提供消息中心,以处理请求。注意信息中心是必须的,否则用户之间无法进行互动。
例如下图中星佳城市的信息中心:
fusion2.api.sendrequest_2.png

FAQ

详见:FusionAPI调用相关问题

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

Copyright © 1998 - 2018 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部