应用框架开发文档
(→未登录状态访问应用参数) |
(→FAQ) |
||
(未显示2个用户的9个中间版本) | |||
第59行: | 第59行: | ||
如果接入方需要iframe 高度自适应等功能,请引入我们提供的 JS 包 | 如果接入方需要iframe 高度自适应等功能,请引入我们提供的 JS 包 | ||
+ | |||
+ | |||
+ | http://www.sinaimg.cn/blog/developer/wiki/weibo_app_workflow.png | ||
第80行: | 第83行: | ||
假设您的站内应用地址是:apps.weibo.com/liwu,iframe中应用实际地址是:www.liwu.com。 当浏览器地址栏是apps.weibo.com/liwu/demo/a1.php时,iframe中的页面会定位至www.liwu.com/demo/a1.php | 假设您的站内应用地址是:apps.weibo.com/liwu,iframe中应用实际地址是:www.liwu.com。 当浏览器地址栏是apps.weibo.com/liwu/demo/a1.php时,iframe中的页面会定位至www.liwu.com/demo/a1.php | ||
− | |||
==应用框架 POST 参数== | ==应用框架 POST 参数== | ||
第88行: | 第90行: | ||
===未登录状态访问应用参数=== | ===未登录状态访问应用参数=== | ||
− | |||
− | |||
− | |||
{| border="1" | {| border="1" | ||
第127行: | 第126行: | ||
===登录状态访问应用,自动授权成功参数=== | ===登录状态访问应用,自动授权成功参数=== | ||
− | + | {| border="1" | |
− | + | |- | |
− | + | ! 参数名 | |
− | + | ! 必选 | |
− | + | ! 类型 | |
− | + | ! 说明 | |
− | + | |- | |
− | + | | user | |
− | + | | true | |
− | + | | Array | |
− | + | | 当前用户对象 | |
− | + | |- | |
− | + | | algorithm | |
− | + | | true | |
− | + | | String | |
− | + | | 签名算法,暂时用 HMAC-SHA256 | |
− | + | |- | |
− | + | | issued_at | |
− | + | | true | |
− | + | | Int | |
− | + | | 服务端生成时间,unix timestamp 格式 | |
− | + | |- | |
− | + | | expires | |
− | + | | true | |
− | + | | Int | |
− | + | | access_token 过期时间,unix timestamp 格式 | |
− | + | |- | |
− | + | | oauth_token | |
− | + | | true | |
− | + | | String | |
− | + | | access_token | |
− | + | |- | |
− | + | | user_id | |
− | + | | true | |
− | + | | unit64 | |
− | + | | 当前用户微博 user id | |
− | + | |- | |
− | + | | referer | |
− | + | | true | |
− | + | | String | |
− | + | | 页面的 document.referrer | |
− | + | |- | |
− | + | | scope | |
− | + | | true | |
− | + | | String | |
− | + | | 应用的 scope 参数 | |
− | + | |- | |
− | + | | ext_data | |
− | + | | false | |
− | + | | String | |
− | + | | 扩展字段,暂时用不上 | |
− | + | |- | |
− | + | | ouid | |
− | + | | false | |
− | + | | uint64 | |
− | + | | 当前应用的安装者 uid,站内应用无此参数 | |
− | + | |- | |
− | + | |} | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
使用 PHPSDK 从 signed_request 提取参数: | 使用 PHPSDK 从 signed_request 提取参数: | ||
第212行: | 第197行: | ||
} | } | ||
</pre> | </pre> | ||
+ | |||
+ | ==Web版应用客户端 JS 包使用说明== | ||
+ | |||
+ | ===引入JS文件=== | ||
+ | |||
+ | <pre> | ||
+ | <script src="http://tjs.sjs.sinajs.cn/open/thirdpart/js/frame/appclient.js" type="text/javascript" charset="utf-8"></script> | ||
+ | </pre> | ||
+ | |||
+ | |||
+ | 如果你在 open.weibo.com 设置了应用的高度为自适应,且引入了这个 JS 到需要自适应高度的页面,你的应用就能自动适应高度了。 | ||
+ | |||
+ | |||
+ | 为了对页面性能产生最小的影响,建议此文件放在 </body> 之前 | ||
+ | |||
+ | ===API方法=== | ||
+ | |||
+ | 1、触发行为 | ||
+ | |||
+ | <pre>App.trigger('<cmd>', ['<param>', ['<function>]]);</pre> | ||
+ | |||
+ | *<cmd> 必选参数,指定行为的名称 | ||
+ | *<param> 可选参数,指定调用行为的参数 | ||
+ | *<function> 可选参数,指定行为的异步回调函数 | ||
+ | |||
+ | <cmd> 列表如下: | ||
+ | |||
+ | setPageHeight 设置iframe自身的高度: | ||
+ | <pre>App.trigger('setPageHeight ', '500');</pre> | ||
+ | |||
+ | |||
+ | scrollTo 改变父页面滚动条位置: | ||
+ | |||
+ | 设置父页面滚动到顶部位置200px的地方 | ||
+ | <pre>App.trigger('scrollTo', 200);</pre> | ||
+ | |||
+ | 设置父页面滚动到iframe的顶部位置 | ||
+ | <pre>App.trigger('scrollTo', 'page');</pre> | ||
+ | |||
+ | parentInfo 获取父页面信息 | ||
+ | <pre> | ||
+ | App.trigger('parentInfo', function(parentWin) { | ||
+ | console.log(parentWin); | ||
+ | // parentWin.iframe.width 获得iframe宽度 | ||
+ | // parentWin.iframe.height 获得iframe高度 | ||
+ | // parentWin.iframe.left 获得iframe距离父页面左端的距离 | ||
+ | // parentWin.iframe.top 获得iframe距离父页面顶端的距离 | ||
+ | // parentWin.page.height 父页面高度 | ||
+ | // parentWin.page.width 父页面宽度 | ||
+ | // parentWin.page.height 父页面高度 | ||
+ | // parentWin.page.scrollTop 父页面的滚动条scrollTop | ||
+ | // parentWin.page.scrollLeft 父页面的滚动条scrollLeft | ||
+ | // parentWin.page.url 父页面url | ||
+ | // parentWin.win.width 父页面窗口宽度 | ||
+ | // parentWin.win.height 父页面窗口高度 | ||
+ | }); | ||
+ | </pre> | ||
+ | |||
+ | login 唤起登录浮层 应用支持未登录状态下访问,必要的时候唤起登录浮层来登录微博。 | ||
+ | <pre> | ||
+ | App.trigger('login', { | ||
+ | // 请注意,redirect_uri 是登录成功后回调的 URL,必须传的是 *.weibo.com 下的 URL,不支持第三方的地址 | ||
+ | 'redirect_uri' : encodeURIComponent('http://apps.weibo.com/1852339337/8s1i6v74?key=g-16504') | ||
+ | }); | ||
+ | </pre> | ||
+ | |||
+ | setTitle 设置父页面标题栏(此API暂未开放) | ||
+ | <pre>App.trigger('setTitle', "Home-My Application Name");</pre> | ||
+ | |||
+ | |||
+ | 2、事件监听 (on/off) | ||
+ | |||
+ | <pre> | ||
+ | App.on('<event>;', '<function>'); | ||
+ | App.off('<event>', '<function>'); | ||
+ | </pre> | ||
+ | |||
+ | *<event>为必选参数,指定要监听的事件称 | ||
+ | *<function>为可选参数,指定事件的异步回调函数 | ||
+ | |||
+ | <event> 列表如下: | ||
+ | |||
+ | scroll 外层滚动页面的事件 | ||
+ | |||
+ | <pre> | ||
+ | //绑定 scroll 事件 | ||
+ | App.on('scroll', function(scrollPos){ | ||
+ | console.log(scrollPos); | ||
+ | // scrollPos.top 纵向滚动条距顶部距离 | ||
+ | // scrollPos.left 横向滚动条距左边框距离 | ||
+ | }) | ||
+ | </pre> | ||
+ | |||
+ | <pre> | ||
+ | //解绑 scroll 事件 | ||
+ | App.off('scroll', <function>) | ||
+ | </pre> | ||
+ | |||
+ | resize 外层改变页面大小的事件 | ||
+ | <pre> | ||
+ | //绑定 resize 事件 | ||
+ | App.on('resize', function(parentWin) { | ||
+ | console.log(parentWin); | ||
+ | // parentWin.page.width 父页面宽度 | ||
+ | // parentWin.page.height 父页面高度 | ||
+ | // parentWin.win.width 父页面窗口宽度 | ||
+ | // parentWin.win.height 父页面窗口高度 | ||
+ | }); | ||
+ | </pre> | ||
+ | |||
+ | <pre> | ||
+ | //解绑 resize 事件 | ||
+ | //App.off('resize', <function>) | ||
+ | </pre> | ||
+ | |||
+ | ==FAQ== | ||
+ | |||
+ | 1、我的应用不升级,还能继续使用吗? | ||
+ | |||
+ | 答:不主动升级的应用,将维持原版,不受任何影响。 | ||
+ | |||
+ | |||
+ | 2、我如何区分是Web版还是H5版? | ||
+ | |||
+ | 答:第三方应用中,PHP 可以根据页面的 userAgent 来判断是不是移动设备,从而决定输出 H5 的内容还是 Web 版的内容。 | ||
+ | |||
+ | |||
+ | 3、我的应用地址是http://apps.weibo.com/1785311805/8rYu1uHD ,应用框架嵌入的是我的应用首页,能直接访问到某个具体的页面吗,例如:http://apps.weibo.com/1785311805/8rYu1uHD/test.php?param1=abc ? | ||
+ | |||
+ | 答:可以,目前框架支持带全 URL。 | ||
+ | |||
+ | |||
+ | 4、我的应用为何没有自适应高度? | ||
+ | |||
+ | 答:请检查两个地方:open.weibo.com 的应用管理中心,是否将应用高度自适应勾选了;而是否部署了客户端 JS。如果都设置了还没有自适应高度,请寻找页面底部的联系方式。 | ||
+ | |||
+ | |||
+ | 5、我的页面大于 5000px,被框架挡住了,怎么办? | ||
+ | |||
+ | 答:考虑到绝大多数应用不会有超过 5000px,所以我们做了限制,自适应不能超过这个限制。如果你一定要突破这个限制,请调用:App.trigger("setPageHeight", "6000"); | ||
+ | |||
+ | |||
+ | 6、为什么我会出现双层导航? | ||
+ | |||
+ | 你需要给链接增加属性 target="_top" |
2014年4月21日 (一) 11:43的最后版本
此文档只针对新接入的第三方应用,原有的站内应用、企业应用(专业版应用)、Page应用,需要第三方进行代码升级并在平台网站升级后才能使用。
为了规范第三方应用接入,提供一致性的开发接入模式,2014年微博对原有的三种应用框架体系进行整合,形成一套新的框架体系。
目录 |
名词解释
应用接入方:开发应用的第三方团队或个人。
应用框架:微博向应用接入方提供的整套解决方案。
应用 iframe 外框:微博开放平台提供的应用承载的页面,内部通过 iframe 嵌入接入方的页面。
新版应用框架特性
- 快速授权:如果用户在登录状态访问应用,新的框架将默认完成授权,并将 access_token 信息传递给第三方。
- 统一接入方式和参数:无论是哪种类型的应用,无论是 Web 版还是客户端嵌入的 H5 版本,客户端收到的参数都是相同的,接入方式也基本上都相同。应用内可以通过浏览器 userAgent 来区分是 Web 端还是 H5 状态。**新增应用分享和赞。直接将应用分享到微博,并生成卡片展示,快速传播。
- 应用支持未登录访问:未登录微博也可以浏览应用,必要的时候通过我们的 JS 客户端唤起登录浮层。
- 应用宽度调整为 940px:不支持原来的 760px,原来的 950 px 改为 940px。
新应用框架范例展示
企业应用
应用名:北京汽车网上4S店
预览图:Web版、H5版
站内应用
应用名:三格半
预览图:Web版
Page应用
应用名:
预览图:Web版、H5版
创建应用
应用框架实现方式及页面流程
实现方式
应用框架采用 iframe 嵌套,通过 POST 形式将参数传递给应用接入方提供的应用地址
页面流程
应用外框架获取当前登录用户信息,自动完成应用授权,并将 access_token 等信息加密
应用外框架解析当前访问的 URL,并解析为对应的第三方页面 URL,将加密的 access_token 等信息通过 POST 传递给第三方
第三方使用微博提供的 SDK (如 PHPSDK 等),将加密的信息解密
如果接入方需要iframe 高度自适应等功能,请引入我们提供的 JS 包
应用内支持两类形式的超链接:
1)在当前窗口跳转,地址栏不变
<a href="应用实际地址链接" target="_self"></a>
或
<a href="应用实际地址链接"></a>
2) 在当前窗口打开,刷新整个框架,地址栏改变
<a href="http://apps.weibo.com/xxx" target="_top"></a>
直接跳转至指定页面:
假设您的站内应用地址是:apps.weibo.com/liwu,iframe中应用实际地址是:www.liwu.com。 当浏览器地址栏是apps.weibo.com/liwu/demo/a1.php时,iframe中的页面会定位至www.liwu.com/demo/a1.php
应用框架 POST 参数
应用框架会通过 POST 形式,发送给第三方页面一个加密后的参数 signed_request,这个参数可以使用 PHPSDK 之类进行解密。
未登录状态访问应用参数
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
user | true | Array | 当前用户对象 |
algorithm | true | String | 签名算法,暂时用 HMAC-SHA256 |
issued_at | true | Int | 服务端生成时间,unix timestamp 格式 |
referer | true | String | 页面的 document.referrer |
ouid | false | uint64 | 当前应用的安装者 uid,站内应用无此参数 |
登录状态访问应用,自动授权成功参数
参数名 | 必选 | 类型 | 说明 |
---|---|---|---|
user | true | Array | 当前用户对象 |
algorithm | true | String | 签名算法,暂时用 HMAC-SHA256 |
issued_at | true | Int | 服务端生成时间,unix timestamp 格式 |
expires | true | Int | access_token 过期时间,unix timestamp 格式 |
oauth_token | true | String | access_token |
user_id | true | unit64 | 当前用户微博 user id |
referer | true | String | 页面的 document.referrer |
scope | true | String | 应用的 scope 参数 |
ext_data | false | String | 扩展字段,暂时用不上 |
ouid | false | uint64 | 当前应用的安装者 uid,站内应用无此参数 |
使用 PHPSDK 从 signed_request 提取参数:
if(!empty($_REQUEST["signed_request"])){ $o = new SaeTOAuth( WB_AKEY , WB_SKEY ); $data = $o->parseSignedRequest($_REQUEST["signed_request"]); if($data == '-2'){ die('sign is error!'); } else { $_SESSION['oauth2'] = $data; } }
Web版应用客户端 JS 包使用说明
引入JS文件
<script src="http://tjs.sjs.sinajs.cn/open/thirdpart/js/frame/appclient.js" type="text/javascript" charset="utf-8"></script>
如果你在 open.weibo.com 设置了应用的高度为自适应,且引入了这个 JS 到需要自适应高度的页面,你的应用就能自动适应高度了。
为了对页面性能产生最小的影响,建议此文件放在 </body> 之前
API方法
1、触发行为
App.trigger('<cmd>', ['<param>', ['<function>]]);
- <cmd> 必选参数,指定行为的名称
- <param> 可选参数,指定调用行为的参数
- <function> 可选参数,指定行为的异步回调函数
<cmd> 列表如下:
setPageHeight 设置iframe自身的高度:
App.trigger('setPageHeight ', '500');
scrollTo 改变父页面滚动条位置:
设置父页面滚动到顶部位置200px的地方
App.trigger('scrollTo', 200);
设置父页面滚动到iframe的顶部位置
App.trigger('scrollTo', 'page');
parentInfo 获取父页面信息
App.trigger('parentInfo', function(parentWin) { console.log(parentWin); // parentWin.iframe.width 获得iframe宽度 // parentWin.iframe.height 获得iframe高度 // parentWin.iframe.left 获得iframe距离父页面左端的距离 // parentWin.iframe.top 获得iframe距离父页面顶端的距离 // parentWin.page.height 父页面高度 // parentWin.page.width 父页面宽度 // parentWin.page.height 父页面高度 // parentWin.page.scrollTop 父页面的滚动条scrollTop // parentWin.page.scrollLeft 父页面的滚动条scrollLeft // parentWin.page.url 父页面url // parentWin.win.width 父页面窗口宽度 // parentWin.win.height 父页面窗口高度 });
login 唤起登录浮层 应用支持未登录状态下访问,必要的时候唤起登录浮层来登录微博。
App.trigger('login', { // 请注意,redirect_uri 是登录成功后回调的 URL,必须传的是 *.weibo.com 下的 URL,不支持第三方的地址 'redirect_uri' : encodeURIComponent('http://apps.weibo.com/1852339337/8s1i6v74?key=g-16504') });
setTitle 设置父页面标题栏(此API暂未开放)
App.trigger('setTitle', "Home-My Application Name");
2、事件监听 (on/off)
App.on('<event>;', '<function>'); App.off('<event>', '<function>');
- <event>为必选参数,指定要监听的事件称
- <function>为可选参数,指定事件的异步回调函数
<event> 列表如下:
scroll 外层滚动页面的事件
//绑定 scroll 事件 App.on('scroll', function(scrollPos){ console.log(scrollPos); // scrollPos.top 纵向滚动条距顶部距离 // scrollPos.left 横向滚动条距左边框距离 })
//解绑 scroll 事件 App.off('scroll', <function>)
resize 外层改变页面大小的事件
//绑定 resize 事件 App.on('resize', function(parentWin) { console.log(parentWin); // parentWin.page.width 父页面宽度 // parentWin.page.height 父页面高度 // parentWin.win.width 父页面窗口宽度 // parentWin.win.height 父页面窗口高度 });
//解绑 resize 事件 //App.off('resize', <function>)
FAQ
1、我的应用不升级,还能继续使用吗?
答:不主动升级的应用,将维持原版,不受任何影响。
2、我如何区分是Web版还是H5版?
答:第三方应用中,PHP 可以根据页面的 userAgent 来判断是不是移动设备,从而决定输出 H5 的内容还是 Web 版的内容。
3、我的应用地址是http://apps.weibo.com/1785311805/8rYu1uHD ,应用框架嵌入的是我的应用首页,能直接访问到某个具体的页面吗,例如:http://apps.weibo.com/1785311805/8rYu1uHD/test.php?param1=abc ?
答:可以,目前框架支持带全 URL。
4、我的应用为何没有自适应高度?
答:请检查两个地方:open.weibo.com 的应用管理中心,是否将应用高度自适应勾选了;而是否部署了客户端 JS。如果都设置了还没有自适应高度,请寻找页面底部的联系方式。
5、我的页面大于 5000px,被框架挡住了,怎么办?
答:考虑到绝大多数应用不会有超过 5000px,所以我们做了限制,自适应不能超过这个限制。如果你一定要突破这个限制,请调用:App.trigger("setPageHeight", "6000");
6、为什么我会出现双层导航?
你需要给链接增加属性 target="_top"