Dialog

Dialog API是一种可视化接口,它有一套固定的用户交互界面,由于在使用时需要用户确认后才能完成操作,因此这类API无需用户授权(有特殊说明的除外)。Dialog API提供不同的显示模式,以适用于不同的终端设备。

调用方法

由于每个dialog都需要用户的确认才能生效,因此dialog是无需用户的授权就可以使用。
Dialog API 不需要access_token或者session_key方式规定的参数,有特殊说明的除外。

公共参数
参数是否必填说明
displayTRUEdialog弹出框的展示方式
站内组件支持popup、iframe,连接网站支持popup方式,移动端请使用WAP方式
redirect_uriTRUE回调地址,也可以作为点击确认后的跳转地址(由need_redirect决定),
必须与组件回调地址或者网站地址在同一个域。
need_redirectFALSE是否跳转到redirect_uri指定的地址,0/1-跳转/不跳转,默认为0不跳转。
0-不跳转,redirect_uri仅仅作为回调
1-跳转,回调参数作为参数加到redirect_uri以GET方式回调。如用户按取消,跳转前会在redirect_uri中追加fragment:#cancel=1。
连接网站不进行跳转,这个字段不用填。
app_idTRUE申请应用时获得的APPID
使用方法

每个dialog的url都是以”http://api.kaixin001.com/dialog/{dialog name}“开头的,其中{dialog name}为用户所触发的dialog的名称,参数以GET方式传入。

以feed dialog为例:

http://api.kaixin001.com/dialog/feed?
display=iframe
&redirect_uri=http%3A%2F%2Fwww.kaixin001.com%2Fjianfeng%2Ftestapp_bak%2Fwelcome.php%3F
&linktext=baidu
&link=http%3A%2F%2Fwww.kaixin001.com
&text=11111
&picurl=http%3A%2F%2Fpic.kaixin008.com.cn%2Fpic%2Fapp%2F23%2F1%2F9000_dnew-ad.gif
&app_id=100003386
&need_redirect=0

显示模式

Dialog API支持多种显示模式(display参数),以适应不同的应用终端,分别为popup、iframe、wap、app,各个显示模式的应用场景以及使用限制如下。

popup

popup:用户触发dialog后,会在当前页面上方弹出一个新窗口展现dialog,整个页面不会发生跳转。
适用于站外应用,比如第三方连接网站可以使用此模式。

界面:

iframe

使用iframe弹出浮层模式需要引用JS-SDK:

<script src="http://s.kaixin001.com.cn/js/openapp-8.js" language="JavaScript"></script>

示例:

<script>
function openFeedDlg()
{
	/*  参数说明:
		app_id		申请应用时获得的APPID
		display	dialog弹出框的展示方式(iframe--弹出层的方式 popup--新窗口方式)
		redirect_uri 	回调地址 
		linktext 	动态里面的链接文字,不超过15个汉字。例如,去帮忙 
		link 		动态里的链接地址,必须以http或https开头。 
		text 		发送动态所使用的文案,不超过60个汉字,否则会被截断。该文案可以有{_USER_} {_USER_TA_}变量,解析时会被替换为当前用户名字和他/她。例如,动态文案:{_USER_} 在做XX任务时遇到了强大的XX,快去帮帮{_USER_TA_}! 
		picurl 	发送动态所使用的图片地址,如果动态分享中需要发布图片,则此项必填。图片尺寸为80×80,否则会被压缩/拉伸为80×80 
		cb 		js回调函数
	*/
        var p = {"app_id":<?=KX_APPID ?>,"display":"iframe","redirect_uri":"<?=KX_CALLBACK_URL ?>","linktext":"去帮忙","link":"http://www.kaixin001.com", "text":"{_USER_} 在做XX任务时遇到了强大的XX,快去帮帮{_USER_TA_}!"};
        p.cb = function(v){console.log(v);};//用户点取消时v.cancel==1
        KX.feed(p);
}
</script>
<input type="button" name="feed" value="发布动态" onclick="openFeedDlg();" />

界面:

WAP

WAP:此模式适用于移动终端。用户触发dialog后,服务器会返回HTML到移动端,以网页的形式展示出来。
适用于WAP网站和手机APP,服务器会根据用户的UA去判断返回什么样式的页面

界面:
wap 2.0版

iphone版

APP

app:适用于带有触摸屏的智能移动设备上的APP。此模式暂不支持,敬请期待。

接口回调

在用户完成操作后,开放平台会将结果通知第三方应用。第三方应用需要提供一个回调地址(通过redirect_uri指定)来接收接口的回调参数。

redirect_uri规范

应确保redirect_uri是可以在互联网上直接被访问的,切勿添加登录验证等功能,也不能使用本地或局域网内部的地址。
Dialog回调地址及签名验证检查

通信方式

GET

例如:您的接口地址为http://www.mydomain.com/callback.php,开放平台将会使用以下方式把参数传递给您:http://www.mydomain.com/callback.php?sig=xxxx&uid=xxxx

回调参数

Dialog/Feed回调参数

参数名说明
uid执行当前操作的用户UID
feedid动态ID
ctime执行回调函数的时间戳
callbackkey用户操作的代码。具体的代码所代表含义请参见以下操作代码对照表。某些接口提供了可选的callbackkey参数的,表示该接口回调操作代码是可以自定义的
sig数字签名

Dialog/Invitation和Dialog/Sysnews回调参数

参数名说明
uid执行当前操作的用户UID
num接收系统消息或邀请用户的数量
fuids接收系统消息或邀请的用户的uid,以逗号隔开
ctime执行回调函数的时间戳
callbackkey用户操作的代码。具体的代码所代表含义请参见以下操作代码对照表。某些接口提供了可选的callbackkey参数的,表示该接口回调操作代码是可以自定义的
sig数字签名

Dialog/Pay回调参数

参数名说明
uid执行当前操作的用户UID
orderid订单号
amount支付的开心币
from来源
status订单支付状态。1为支付成功
pid流水号,用于对账
testtest值为非空或非零值,说明使用测试开心币进行的支付
ctime回调时间
sig数据签名。用来判断请求是否由开心网所发出(与API1.2验证方法不同
callbackkey用户操作的代码。具体的代码所代表含义请参见以下操作代码对照表。
某些接口提供了可选的callbackkey参数的,表示该接口回调操作代码是可以自定义的

操作代码对照表

操作代码说明
sysnews系统消息
invite邀请好友
newsfeed好友动态
pay支付
验证回调

由于您的接口必须是在互联网上可直接被访问的(不可添加任何形式的身份验证)。为保证接口访问是合法的,我们为大家提供了以下的方式来验证这次访问是否由开心网开放平台所发起。

回调参数中的sig参数用来验证这次回调是否是由开心网发来的。验证sig的方法参考示例代码。

PHP示例:

/**
* 参数:
* $params: 回调接口获取到的所有参数。比如$_GET
* $secrect: 第三方应用在开心网的secrect
* 
* 返回值:
* 如果签名验证正确,返回true,否则返回false
*/
function checkSign($params, $secrect)
{
    $sig_raw = $params['sig'];
    unset($params['sig']);
    ksort($params);   //参数按照key进行排序
    $query = http_build_query($params);
    $sig = md5($query.$secrect);
    if($sig == $sig_raw)
    {
         return true;
    }
    return false;
}
?>

已开放的Dialog API

/dialog/feed 发布好友动态(有交互界面)
/dialog/invitation 发送邀请(有交互界面)
/dialog/sysnews 发送系统消息(有交互界面)
/dialog/pay 支付接口(有交互界面)
/dialog/repaste 转帖接口(有交互界面)
/dialog/authorizeqq QQ绑定接口(有交互界面)