fusion2.dialog.invite

目录

What's New?

2014年4月21日起,接口新增邀请到群会话功能,极大增强了邀请的社交转化能力。

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

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

2012年12月20日起,为了提高邀请质量,1个用户在1个应用里,每天只能给同一个好友发送1次邀请。

2012年10月08日起,为了提高邀请的转化率,1个用户1次最多能选择10个好友。
如果是开发者传入被邀请好友的openid,则参数“receiver”传入的openid的个数如果多于10个,截取前面10个进行验证后显示。因此建议开发者优先选择最有可能接受邀请的用户的openid传入。

2012年9月13日起,支持QQ空间的邀请feeds中展示开发者传入的图片和文字,使feeds更生动形象,更有吸引力。具体图片与文字的要求请查看参数说明中“msg”和“img”的描述。

2012年8月31日起,支持开发者传入被邀请好友的openid,直接给用户弹出确认框(详见接口调用说明中的receiver参数)。

1 功能说明

1. 接口类型:前端JS接口。
2. 接口功能:邀请好友开通应用,用于提升应用安装量。
3. 功能描述:
(1)要实现邀请好友开通功能,只需在应用的前端页面代码中调用本接口,并在应用的界面上放置类似“邀请好友”的按钮。
(2)用户在应用中点击“邀请好友”按钮后,即可在打开的好友邀请弹框中选择要邀请的好友。
(3)支持开发者传入被邀请好友的openid,此时直接给用户弹出确认框,不再打开好友邀请弹框由用户选择要邀请的好友(仅支持空间和朋友平台)。如果用户刚进入应用,请使用好友邀请弹框模式,如果应用使用确认框模式,申请接口v3/relation/get_rcmd_friends的权限时,腾讯方将不予通过。
(4)发送邀请后,好友的个人中心将看到邀请feeds,还会收到QQTips。
(5)好友点击QQTips或feeds中的应用链接,即可进入应用。
(6)支持邀请结果回传(仅支持空间和朋友平台)。用户点击邀请弹框中的发送按钮后,回传给应用发起邀请者的openid,被邀请者的openids。该特性使应用可根据用户发送邀请的数量来做活动(例如“今天你邀请10个未安装游戏的好友,就能获取普吉岛豪华双人游”),从而刺激邀请的发送量;也可以根据邀请的转换率来调整游戏的合理性、平衡性(例如游戏中某个关卡的过关条件是“成功邀请5个好友来玩游戏”,但应用发现用户已经发起邀请超过100次了,都没有带来5个好友来安装应用,则及时调整,适当降低要求,以减少用户挫败感)。
(7)关于如何判断用户是通过邀请进入应用的。用户进入应用后,应用可调用接口v3/spread/verify_invkey判断该用户是否是由某个用户邀请过来的,若是,则应用可给发送邀请的用户赠送礼品。

4. 接口调用限制
(1)应用状态:应用上线前,调用本接口只能弹框,弹框中不会出现好友信息,不会发送邀请。上线后才能发送邀请。
(2)支持的平台:开发者可以直接传入被邀请好友的openid,以及邀请结果回传的功能,目前仅支持空间和朋友平台,不支持微博平台。
(3)调用的频率限制:详见社交渠道使用优化指引

2 场景说明

2.1 入口说明

建议在应用的顶部添加类似“邀请好友”的按钮,位置明显,方便用户操作。

用户点击按钮后,会根据开发者调用接口时传入的参数弹出不同的弹框:
方案1:没有传入被邀请好友的openid时,会弹出带有好友选择器的弹框,由用户来选择要邀请的好友。
方案2:如果传入被邀请好友的openid时,直接弹出确认框,用户不需要选择要邀请的好友,点击“确定”后即可给openid对应的好友发送邀请。

2.2 弹框效果展示

方案1:弹出好友邀请框
空间和朋友平台,与微博平台的弹框展现方式不同。
1. 空间和朋友平台好友邀请弹框中有如下元素:
(1)弹框中列出未安装应用的好友。
(2)弹框中有应用的图片,建议为应用的图标或者与邀请相关的主题图片。
(3)弹框中有邀请好友的内容描述,吸引用户点击storyfeeds进入应用。
好友邀请弹框示例如下图所示:
fusion2.dialog.invite-4.221.png

2. 微博平台好友邀请弹框中有如下元素:
(1)弹框中列出未安装应用的好友。
(2)用户选择邀请的好友点击“提交”后,弹出“发送请求”弹框,弹框中显示已邀请的好友和信息输入框,用户可以自己输入邀请信息。
好友邀请弹框示例如下图所示:
invite_friend_3.png

方案2:弹出确认框
仅支持空间和朋友平台,不支持微博平台。
确认弹框中有如下元素:
(1)弹框中列出被邀请的好友。
(2)弹框中有应用的图片,建议为应用的图标或者与邀请相关的主题图片。
(3)弹框中有邀请好友的内容描述,吸引用户点击storyfeeds进入应用。
确认弹框示例如下图所示:
invite_friend_11.png

2.3 结果展现

朋友和空间平台
1. 用户发送邀请成功后,相应的好友在其QQ客户端会收到会话或tips提醒,点击链接即可进入应用。
以QQ空间为例,tips示例如下:
fusion2.dialog.invite-4.22.2.png
invite_friend_9.png
2. 用户发送邀请成功后,相应的好友的空间的个人主页上会出现该邀请的feeds,点击链接即可进入应用:
invite_friend_10.png

微博平台
用户发送邀请成功后,在微博的个人主页上,相应的好友会收到被@的通知,点击链接即可进入应用。
invite_friend_6.png

3 接口调用说明

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

3.1 参数说明

参数名称 是否必须 类型 描述
receiver string数组 参数描述:表示被邀请好友的openid,只能传1个未安装应用的好友的openid(可通过v3/relation/get_rcmd_friends接口获取平台推荐的好友)。

如果传多个openid,只取第1个进行验证后显示。
如果是弹出用户选择邀请好友弹框,则不需要传入该参数。
non-hosting应用由于不能调用好友关系链接口来获取openid,只能弹出用户选择邀请好友弹框。

msg string 参数描述:邀请好友时,发送给好友的邀请信息。请尽量简洁生动,能够吸引用户进入应用。如果不传,则默认为应用创建时输入的应用描述。

目前在朋友及空间的邀请弹框中使用到该消息,其它地方使用应用创建时输入的应用描述。
长度限制:控制在35个汉字以内。
文本显示位置:见上文2.2节朋友及空间平台好友邀请弹框中左下角的邀请信息。在QQ空间的邀请feeds中,也会显示该邀请信息。

img string 参数描述:邀请配图的URL,用于在空间邀请feeds中展示。如果不传,则默认在弹框中显示应用的icon。

注意:QQ空间邀请的QQtips中的图片是应用的图片或用户头像,不是这里传入的图片。
微博平台不可使用该参数。
图片显示位置:见上文2.2节朋友及空间平台好友邀请弹框中左下角的图片。在QQ空间的邀请feeds中,也会显示该图片。

图片文件大小:无要求。
图片格式:.jpg, .png, .jpeg,其它待补充。
图片规格:75×75px。
是否自动缩放:是。但建议按照图片规格75×75px准备图片。若满足规格要求,则feeds中显示该图片;不满足则显示应用的icon。
图片URL域名限制:
hosting应用要求将图片存放在APP域名下或腾讯CDN。
non-hosting应用要求将图片上传到该应用开发者QQ号对应的QQ空间相册中。即non-hosting应用图片域名必须为:qq.com、pengyou.com、qzoneapp.com、qqopenapp.com、tqapp.cn。

source string 参数描述:应用自定义参数,邀请好友成功后,被邀请方通过邀请链接进入应用时会携带该参数并透传给应用,用于识别用户来源。

长度限制:这里的参数会被URL编码,需要注意编码后的长度不允许超过900个字符。
例如:
用户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)发起邀请者的openid: opt.inviter
(2)被邀请者的openids: opt.invitees
(3)被邀请者的数量: opt.invitees.length
(4)被邀请群的openids:opt.invitegroups
(5)被邀请群的数量:opt.invitegroups.length

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

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

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

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

3.2 调用示例

fusion2.dialog.invite

({

  receiver : "00000000000000000000000000009FED",


  msg  : "邀请你来玩~",


  img : "http://qzonestyle.gtimg.cn/qzonestyle/act/qzone_app_img/app353_353_75.png",
  
  source : "domain=s4.app12345.qqopenapp.com",


  context : "invite",


  onSuccess : function (opt) {  alert("邀请成功"); },


  onCancel : function (opt) { alert("邀请取消"); },


  onClose : function (opt) {  alert("邀请关闭"); }

});

4. 关于“邀请好友即赠送礼品”功能的说明

1. “邀请好友即赠送礼品”需要开发者在程序中判断添加了该应用的用户是由哪一个用户邀请过来的,即需要验证好友邀请的加密串,腾讯提供了验证接口:v3/spread/verify_invkey
2. 2012年2月13日起,赠送加密串invkey等参数开始支持多区多服应用,因此多区多服应用也可以使用邀请好友即赠送礼品功能。

FAQ

详见:FusionAPI调用相关问题

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

Copyright © 1998 - 2017 Tencent. All Rights Reserved.

腾讯公司 版权所有

有问必答 返回顶部