fusion2.dialog.sendStory

目录

What's New?

2013年09月11日起,本接口重新支持应用传入被点名好友的openid,即支持传入参数“receiver”。
2013年07月09日起,storyfeeds的标题修改为应用名称,用户可从storyfeeds中直观得知分享来自哪个应用,开发者无须做任何修改。
2013年04月27日起,本接口不再支持应用传入被点名好友的openid,即不再支持传入参数“receiver”。
2013年03月27日起,本接口不支持安装转化率或次日留存率为C的应用传入被点名好友的openid,规则详见:社交渠道使用优化指引
2013年01月24日起,接口调用限制使用了统一规则,请参阅:社交渠道使用优化指引

1 功能说明

1. 接口类型:前端JS接口。
2. 接口功能:游戏故事分享,用于增加应用的注册量,提高用户活跃度。
3. 功能描述:
(1)将用户在应用中的新鲜事或者动态以storyfeeds的形式展现(注:对于QQ空间平台,将展现在平台个人中心的动态中,并沉淀到“分享”模块);
(2)用户通过点击storyfeeds中的操作区文字(如下图红框标识所示的“领取奖励”)可跳转到应用指定页面,达到指定的效果;
(3)应用可选择合适的操作来强化feeds引导。
(4)游戏故事分享弹框中,用户可添加好友进行好友点名,即可@某个好友。用户最多可点名10个好友。
(5)支持开发者传入被点名好友的openid,此时分享弹框的“点名”后会显示开发者传入的openid对应的好友。
(6)为提升该分享功能的效果,平台会自动传入2个最有意愿进入应用的被点名好友的openid(1个为已安装应用的用户,1个为未安装应用的用户),显示在分享弹框的“点名”后。如果开发者有传入被点名好友的openid,以开发者传入的优先,平台和开发者一共最多可传入3个openid。
(7)用户可在弹框中选择是否同时将分享feeds转播到用户的腾讯微博。

4. 接口调用限制:
(1)支持的平台:QQ空间,朋友。
(2)应用状态:应用上线前,调用本接口只能弹框。上线后才能发送feeds。
(3)调用的频率限制:详见社交渠道使用优化指引

5. 特别备注:
本接口将取代分享接口fusion2.dialog.shareshare接口将于2012年12月31日下线,原有已经接入share接口的应用请在2012年12月31日前切换到本接口。
相比share接口,本接口生成的feeds带有操作区文字,使feeds更加生动,可以鼓励用户点击进入应用,从而提高应用的新增用户及用户活跃度:
sendstory8.png

2 场景说明

2.1 入口说明

建议应用在如下情况下,在合适的地方放置类似“分享给好友”或“请好友来帮忙”的按钮,鼓励用户点击:
(1)用户在应用中完成了某项任务时;
(2)用户在应用中获得某些成就时;
(3)用户需要好友帮助时。

用户点击后,应用调用本接口弹出游戏故事分享弹框。

2.2 弹框效果展示

弹框中有如下元素:
(1)弹框中有关于用户向好友分享的内容描述。
(2)弹框中有点名组件,用户点击点名框后的“添加好友”按钮,即可选择要点名的好友。
(3)弹框中有转播到微博的复选框,用户可以选择是否将storyfeeds同时转播到腾讯微博。
(4)弹框中有应用的图片,建议为应用的图标或者与分享相关的主题图片。
(5)弹框中有分享标题和故事摘要,吸引用户点击storyfeeds进入应用。
游戏故事分享弹框示例如下:
sendstory6.png

2.3 结果展现

1. 用户点击“分享”按钮后,会生成storyfeeds。
对于QQ空间平台,该feeds会展现在个人中心的动态中,并沉淀到QQ空间的分享模块。
QQ空间平台的storyfeeds如下图所示:
sendstory7.png

生成的storyfeeds带有操作区文字,使feeds更加生动,能吸引更多好友进入应用。
操作区的文字,目前只能允许四种类型,后续将推出更多类型: 1.进入应用 2.领取奖励 3. 获取能量 4.帮助TA。
这些文字可以用于许多场景:
(1)对于游戏类应用:
-用户在应用中完成了某项任务或者获得某项成就,可以分享一条storyfeeds给好友。见到这个feed的好友点击后也可以获得一些奖励。
示例如下:
sendstory1.png

-用户在使用应用时需要好友帮助,这种帮助无目标性,可以通过发布storyfeeds寻求帮助。见到这个feed的好友点击后可以提供帮助。
示例如下:
sendstory2.png
(2)对于非游戏类应用:
用户在应用中完成了某些测试或者使用某项工具完成了一个任务的时候,可以使用sendstory分享给好友。见到这个feed的好友可以进入应用进行测试或完成任务。
示例如下:
sendstory4.png

2. 如果用户在分享弹框中勾选了“同时转播到我的腾讯微博”,则将相关信息发表到用户的微博,如下图所示:
sendstory10.png

3 接口调用说明

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

3.1 参数说明

参数名称 是否必须 类型 描述
title 必须 string 参数描述:分享的标题。

长度限制:最多不超过25个汉字(50个字符)。
文本显示位置:见上文2.2节弹框图片中的标注5中的标题,该标题也会显示在storyfeeds中。

img 必须 string 参数描述:弹框中显示的应用图片URL。建议为应用的图标或者与分享相关的主题图片。

图片显示位置:见上文2.2节弹框图片中的标注4。
图片文件大小:无要求。
图片格式:.jpg, .png, .jpeg, .gif。
图片规格:120×120px。
是否自动缩放:是。超过120×120px,会按比例进行缩放。
图片URL域名限制:不再对图片URL进行域名限制,应用可传任意图片URL,但所带url不能携带80以外端口。

summary string 参数描述:故事摘要,建议以生动的文字描述故事(完成某项任务或成就,需要好友帮助等),以吸引用户关注度和进入应用的兴趣。

长度限制:最多不超过50个汉字(100个字符),可以为空。
文本显示位置:见上文2.2节弹框图片中的标注5中的故事摘要。
注:此传值不会转发到微博。

msg string 参数描述:弹框中用户输入的分享内容。

长度限制:最多不超过120个汉字(240个字符),可以为空。
文本显示位置:见上文2.2节弹框图片中的标注1。

receiver string数组 参数描述:表示被点名好友的openid。

格式限制:多个openid之间用“,”分隔,最多可传入3个openid(如果多于3个,截取前面3个进行验证后显示),请使用数组的格式。
文本显示位置:如果开发者传入被点名好友的openid,会在弹框的“点名”后显示该好友作为建议,用户点击后即点名成功。见上文2.2节弹框图片中的标注2。

button string 参数描述:操作区的文字,只能填写下面四种中的一种(后续将推出更多类型),如果不填,则默认为"进入应用":
1.进入应用; 2.领取奖励; 3. 获取能量; 4.帮助TA。

文本显示位置:storyfeeds中的操作区文字,见上文3.3节storyfeeds图片中的标注。

source string 参数描述:由开发者自定义该参数内容。

用户发送storyfeeds成功后,应用图标、文字标题、或操作区文字的链接URL中会有app_custom参数,app_custom参数的值与source的值一致。应用可根据好友点击storyfeeds进入应用时CanvasUrl中的app_custom参数的值,判断用户来源。
这里的参数会被URL编码,需要注意编码后的长度不允许超过900个字符。
例如:
用户A分享storyfeeds时,source的值为“openid=001”,用户B分享storyfeeds时,source的值为“openid=002”。用户C分别收到了用户A和用户B的storyfeeds,当用户C点击一个storyfeeds的链接进入应用时,url中会携带app_custom参数,如果app_custom的值为“openid=001”,说明C点击的是A分享的storyfeeds,如果为“openid=002”,说明C点击的是B分享的storyfeeds。

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

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

onSuccess : function (opt) 
  {       
      alert("Succeeded: " + opt.context);  
  }
onShown 参数描述:对话框浮层展现时的回调方法。

方法要求: 回调函数的定义符合标准JS函数定义方式,即:function (opt)。
触发条件:应用调用本接口时,弹出浮层对话框。

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

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

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

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

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

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

3.2 调用示例

fusion2.dialog.sendStory

({

  title :"我的星佳城市升级了!",


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


  summary :"2011年全球游戏巨制《星佳城市》—自由发展农工商,铺路盖楼有理想,全球玩家都在玩,快来星佳做市长!",


  msg:"我的星佳城市已经升到80级了,快来一起当市长吧!",


  button :"获取能量",


  source :"ref=story&act=default",


  context:"send-story-12345",


  onShown : function (opt) 
  {  
      alert("Shown");  
  },


  onSuccess : function (opt) 
  {  
      // opt.context:可选。opt.context为调用该接口时的context透传参数,以识别请求
      alert("Succeeded: " + opt.context);  
  },


  onCancel : function (opt) 
  {  
      // opt.context:可选。opt.context为调用该接口时的context透传参数,以识别请求
      alert("Cancelled: " + opt.context);  
  },


  onClose : function (opt) 
  {  
      alert("Closed"); 
  }

});


3.3 返回码说明

返回码 含义说明
9 请先登录。
1000 参数错误。请从如下几方面进行排查:

1、不是POST请求;
2、必要的cgi入参没填或少填;
3、传入的url不是以 http:// 或 https:// 开头的。

1001 服务器繁忙,请稍候再试。请从如下几个方面进行排查:

1、获取应用信息失败;
2、发送分享失败。

1004 应用不存在。
1005 超过应用发送的频率限制。


FAQ

详见:FusionAPI调用相关问题

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

Copyright © 1998 - 2017 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部