fusion2.dialog.reactive

目录

What's New?

2012年11月1日,接口全量公开,应用无需申请授权即可调用本接口。

2012年08月24日,新增参数“source”,支持开发者自定义,开发者可根据这个参数的内容,判断用户响应的是哪个好友的请求。

2012年08月14日,新增参数“exclude”、“specified”、“only”,支持开发者自定义好友选择器中的对象。

2012年7月31日起,支持召回对象回传。用户点击“召唤老朋友回来”弹框中的发送按钮后,回传给应用的被召回的好友的openid、数量以及召回内容(详见接口调用说明中的onSuccess 参数)。

1 功能说明

1. 接口类型:前端JS接口。
2. 接口功能:召唤老朋友,用于拉回流用户。
3. 功能描述:
(1)要实现“召唤老朋友”功能,只需在应用的前端JS代码中调用本接口,并在应用的界面上放置类似“召唤好友即赢取奖励”的按钮。
(2)调用本接口后,出现“召唤老朋友回来”弹出框, 弹出框中列出平台推荐的一段时间内没来玩的好友;
(3)用户点击弹出框中的“发送”按钮后,即对选中的好友赠送应用礼物(礼物可由用户自己选择,也可由应用指定),以召唤好友回到应用。
(4)为鼓励用户发起召唤,应用可对发起召唤的用户发放相应的奖励。
(5)发送成功后,好友可在应用使用页以及应用中心的应用助手页收到消息。

4. 接口调用限制:
(1)应用状态:应用上线前,调用本接口只能弹框,弹框中不会出现好友信息,不会发送请求。上线后才能发送请求。
(2)支持的平台:本接口目前仅支持QQ空间平台。
(3)调用的频率限制:频率限制暂未补充。但是由于在一天之内推荐的好友不变,因此建议应用内对于同一个用户一天只调用一次本接口。

2 场景说明

2.1 入口说明

应用中应该在合适的地方放置类似“召唤好友即赢取奖励”的链接,鼓励用户点击。

用户点击后的处理方式有2种:
方案1:礼物是固定的,不让用户选择礼物,直接调用接口弹出弹框,在调用接口时提供一个默认的礼物。
方案2:应用做一个选择礼物的页面,用户点击召唤好友的链接后,先出现该页面让用户来选择1个自己想赢得的礼物,用户可以选择1个礼物或跳过,然后应用才用接口弹出弹框。
礼物选择页面示例:
fusion2.dialog.reactive_1.png

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

用户触发2.1中设置的召唤好友的入口后,应用调用召唤好友接口(接口调用详见详见下文第3节说明),弹出“召唤老朋友回来”的弹框。

弹框中有如下元素:
(1)弹框中列出用户推荐一段时间内没来玩的好友(默认全部勾选,用户可以取消勾选)。由于在一天之内推荐的好友是不会变的。建议应用内对于同一个用户一天只调用一次本接口。
(2)弹出框中有应用奖励给发起召唤的用户的物品图片。建议该奖励礼物的设置具有强烈的吸引力,才能让用户有发起召唤的动力。应用必须确保真正的将礼物发放给发起召唤的用户,避免宣传与实际结果不符。
(3)弹出框中有赠送给好友的礼物的图片,以及发送给好友的消息。
如下图所示:
fusion2.dialog.reactive_2.png

2.3 结果展现

发送成功后,好友可收到相关通知,包括:
(1)在应用使用页的应用动态里展示该消息;
(2)在应用中心的应用助手页收到消息,消息格式为“【好友昵称】召唤你回去一起玩:” + 应用调用接口时传的msg。

3 接口调用说明

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

3.1 参数说明

参数名称 是否必须 类型 描述
title 必须 string 参数描述:应用奖励给发起召回的用户的奖品的名称。

长度限制:请控制在6个字以内。
文本显示位置:该字段现在不会显示用户界面上,将作为保留字段。

receiveImg 必须 string 参数描述:应用奖励给发起召回的用户的奖品的图片的URL。建议该奖励礼物的设置具有强烈的吸引力,才能让用户有发起召唤的动力。

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

sendImg 必须 string 参数描述:赠送给好友的礼物的图片。

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

msg string 参数描述:召回老友时的默认赠言,用户可修改,默认赠言请尽量简洁生动。

默认值:如果不传该参数或传空值,则显示系统默认赠言。
长度限制:控制在35个汉字以内。
文本显示位置:见上文2.2节弹框图片中的输入框。

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回调,以识别请求。

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

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

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:用户点击弹出框中的“发送”按钮,提示成功,弹出框关闭。
回调参数及获取方法:可通过如下方式获取该次召回的相关信息:
(1)被召回者的openids: opt.receiver
(2)被召回者的数量: opt.receiver.length
(3)召回时发送的消息内容: opt.msg

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

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

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

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

3.2 调用示例

fusion2.dialog.reactive
({
     title : "飞镖游戏", 


     receiveImg: "http://appimg.qq.com/happyfarm/module/ui/icons/award5.png",


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


     msg: "赶快回来和我一起玩这个应用吧,没有你很孤单啊。", 


    context : "reactive_12345", 


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


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


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


FAQ

详见:FusionAPI调用相关问题

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

Copyright © 1998 - 2017 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部