注意：以下文档只适用于TOP接口，请谨慎使用！
注意：以下文档只适用于TOP接口，请谨慎使用！
调用基础协议，呼出实现者的人。目前千牛有很多资源位都是协议调用者，用户点击后，会呼出对应的协议实现者。
实现基础协议，被调用者呼出，需要根据标准协议实现特定的业务逻辑，不同的插槽有不同的基础协议，是否实现了对应的基础协议会作为准入条件纳入审核。
单纯的呼出某个模块，无后续操作。可以理解为呼出式是没有回调的交互式。
呼出某个模块，在用户完成操作后，把操作结果在回调里返回给呼出方。交互式提供无界面的交互和有界面的交互，无界面的交互模式下，协议实现者处理完后，直接把结果返回给调用者，无需用户介入。目前无界面的交互模式，在PC上有此类方式。
在各个端实现千牛互通协议中心，将千牛（包括插件）的功能大卸八块，每个功能都通过注册协议注册到互通协议的路由中心，所有调用者通过通用协议呼出对应的实现，而不需要管具体的实现者到底是谁。实现者通过回调句柄，输出用户操作结果，而不需要管呼出者到底是谁。
通用协议对外暴露给调用者一共3个概念：
1、 API名称，又叫业务事件{string}[必选]
说白了就是业务API名称，如：商品列表，商品详情，交易列表等。
2、 场景参数{json map}[可选]
不同的场景下，会带上不同的参数，如商品详情需要商品ID，商品列表需要商品状态等，说白了就是调用API需要带的参数。
4、 回调函数{function}[可选]
在交互式的场景中，回调函数负责接收处理完的结果（统一的返回格式）。
基于上述
通用协议对外暴露给实现者一共4个概念：
1、 API Name{string}[必选]
同调用者的事件参数，实现者需要根据场景的不同定位到不同的页面。
2、 场景参数{json map}[可选]
同调用者的场景参数，实现者渲染场景的时候需要根据具体的场景业务参数来渲染页面
3、 response句柄{function}[可选]
如果是一个交互式的场景，在用户处理完后，需要将用户的处理结果回写给调用者，需要通过response句柄来回写（response句柄是通用的，实现者不需要关系调用者是谁）。
4、 千牛基础参数{parameter map}[必选]
千牛基础参数只针对插件实现者会有，千牛基础参数包含插件渲染所必须的一些数据如：用户（uid），授权（authString），来源（from）等。
对于外部ISV而言，JSSDK已经封装了一套接口，接口定义如下：
var application = TOP.mobile.application;
application.request({
event:’itemDetail’,
biz:{
iid:’46745325400042342’
},
success:function(){
},
error:function(){
}
});
查询我可以调用哪些API，可以点击这里：调用者文档
从千牛端呼出ISV插件的时候，一定会带上一些基础的和具体业务无关的参数，如：用户信息（含授权），端来源等,千牛基础参数信息如下：
l 无线端
一级参数 |
二级参数 |
示例 |
说明 |
authString |
usession_id |
19adf0000f395e475e4b7a3577340edec25381f7c518717d4cc301855057121 |
忽略 |
taobao_user_nick |
c%E6%B5%8B%E8%AF%95%E8%B4%A6%E5%8F%B7161 |
主帐号名称，URL编码过的（UTF-8） |
|
re_expires_in |
12493784 |
RefreshToken失效时间，秒单位 |
|
sub_taobao_user_id |
1855057121 |
子账号user_id |
|
r1_expires_in |
12493784 |
开放平台R1授权的失效时间 |
|
timestamp |
1396423815571 |
忽略 |
|
taobao_user_id |
424839708 |
主帐号user_id |
|
w2_expires_in |
0 |
开放平台R2授权的失效时间 |
|
sub_taobao_user_nick |
c%E6%B5%8B%E8%AF%95%E8%B4%A6%E5%8F%B7161%3A%E8%8A%B8%E5%BD%A4 |
子账号名称，URL编码过的（UTF-8） |
|
w1_expires_in |
12493784 |
开放平台W1授权失效的时间 |
|
r2_expires_in |
0 |
开放平台R2授权的失效时间 |
|
token_type |
Bearer |
忽略 |
|
refresh_token |
630171698f009b67a7359d29df9ZZc29832c294ffeae37d1855057121 |
刷新token，ISV应该用不到 |
|
access_token |
6300b1677ba091441819d7cbba4ZZ2f25fbb273ec573bc41855057121 |
用户的授权，可以用来嗲用开放平台 |
|
from |
qianniuAndroid/ qianniuIphone |
来源（IOS 2.3+ android 2.1+） |
|
version |
2.0.3 |
千牛的版本信息（IOS 2.3+ android 2.1+） |
|
uid |
10458887223 |
当前用户的uid |
l PC端：
一级参数 |
示例 |
说明 |
appkey |
11111111 |
开放平台应用appkey |
deviceuuid |
b6c119e63ad8a2f0276c78d8140b6764 |
设备号 |
from |
qianniupc |
请求来源 |
nick |
%e5%95%86%e5%ae%b6%e6%b5%8b%e8%af%95%e5%b8%90%e5%8f%b717 |
当前登录账号的nick，URL编码过的（UTF-8） |
sdkversion |
105000 |
jssdk版本号 |
sessionkey |
6302408c31340199c99ZZ5faaee63875256c654e44fd8f9263664221 |
当前登录账号的授权 |
sign |
8DB2E79BFA8A3F9691C008DBCC622EF6 |
签名 |
slot |
qianniu |
插件类型，有slot跟group |
user_id |
263664221 |
当前登录账号的user_id |
version |
2.00.01N |
千牛客户端版本号 |
插件在被呼起的时候，除了会拿到以上千牛的基础参数外，还会根据不同的呼出事件带上不同的事件参数和事件对于的场景参数。举个例子：当用户收到一个商品变更通知，点击商品信息的时候，会呼出商品的默认插件，默认插件除了能获取到上文中的千牛基础参数外，还能拿到一个事件参数：itemDetail 以及一个场景参数map { iid:489923234342311}
很多ISV 问：怎么判断是从这个事件来的，其实很简单，只要在URL上判断event参数即可，如：如果是选择商品，会有一个参数为：event=itemChoose （ 你可以认为event参数就是API Name）
由于协议兼容问题，商品列表，选择商品，交易列表，交易详情，退款详情需要兼容老的事件参数（需要兼容到3.0版本）。列表如下：
事件 |
老事件参数值 |
新参数值 |
判断示例 |
商品列表 |
event_itemList |
itemList |
event=event_itemList|| itemList |
商品详情 |
event_itemDetail |
itemDetail |
同上 |
交易列表 |
event_tradeList |
tradeList |
同上 |
交易详情 |
event_tradeDetail |
tradeDetail |
同上 |
退款详情 |
event_refundDetail |
refundDetail |
同上 |
在交互式的场景中，当用户处理完后，协议实现者需要把用户的操作结果返回给协议调用者，这个时候，只需要在调用千牛注入给插件的response句柄，将用户操作的结果写入即可。
Response句柄接口定义为：
var application = TOP.mobile.application;
application.response(successJson,errorJson);
例如，在用户选择商品的场景中，当协议调用者调用选择商品的协议，呼出实现者后，用户会在实现者的页面里操作，当用户选择完商品后，实现者需要调用按照返回协议，协议返回值：
var application = TOP.mobile.application;
application.response({
choose:[{
iid:4543543153453234,
title:'商品1'
},{
iid:4543543585453234,
title:'商品2'
}]
},null);
输出结果完成后，如果要关闭当前窗口，请看这里
查询我需要实现哪些协议，请点击这里：实现者文档
