微博应用框架开发文档

原地址：http://beginios.com/javascript/weibo-app-frame#client

此文档只针对新接入的第三方应用，原有的站内应用、企业应用（专业版应用）、Page应用，需要第三方进行代码升级并在平台网站升级后才能使用。

为了规范第三方应用接入，提供一致性的开发接入模式，2014年微博对原有的三种应用框架体系进行整合，形成一套新的框架体系。

文档目录

• 新版应用框架特性
• 创建应用
• 应用框架流程
• 应用框架 POST 参数
• Web版应用客户端 JS 包使用说明
• FAQ
• 联系我们

名词解释

应用接入方：开发应用的第三方团队或个人。

应用框架：微博向应用接入方提供的整套解决方案。

应用 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）在当前窗口跳转，地址栏不变

1 2	<a href="应用实际地址链接" target="_self"></a> 或<a href="应用实际地址链接"></a>

2) 在当前窗口打开，刷新整个框架，地址栏改变

1	<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 提取参数

1 2 3 4 5 6 7 8 9

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; } }

PHPSDK 解密 signed_request 的方法如下，供其他语言参考

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

/** * 解析 signed_request * @param string $signed_request 应用框架在加载iframe时会通过向Canvas URL post的参数signed_request * @return array */ function parseSignedRequest($signed_request) { // 将 $signed_request 参数，用小数点.分隔成数组，下标0的赋值给 $encoded_sig，下标1的复制给 $payload list($encoded_sig, $payload) = explode('.', $signed_request, 2); // 对 $encoded_sig 进行 base64 解码，然后赋值给 $sig $sig = self::base64decode($encoded_sig); // 对 $payload 进行 base64 解码，并将字符串转为 JSON 赋值给 $data $data = json_decode(self::base64decode($payload), true); // 如果 $data 中的 algorithm 不是 HMAC-SHA256，表示数据校验出错，直接返回 -1 if (strtoupper($data['algorithm']) !== 'HMAC-SHA256') return '-1'; // 使用 app secret 对 $payload 进行 sha256 加密 $expected_sig = hash_hmac('sha256', $payload, $this->client_secret, true); // 如果 sha256 加密后的结果和 $sig 是一致的，那么 $data 数据就没问题，直接返回给调用方；否则表示数据校验出错，返回 -2 return ($sig !== $expected_sig)? '-2' : $data; } /** * @ignore */ function base64decode($str) { // 将需要 base64 解码的字符串，按照字符串长度先补上相应的等号（补上等号后的字符串长度应该是4的整数倍），然后将其中的 - 和 _ 分别替换成 + 和 /，然后对处理后的字符串执行 base64 解码 return base64_decode(strtr($str.str_repeat('=', (4 - strlen($str) % 4)), '-_', '+/')); }

Web版应用客户端 JS 包使用说明

引入JS文件

1	<script src="http://tjs.sjs.sinajs.cn/open/thirdpart/js/frame/appclient.js" type="text/javascript" charset="utf-8"></script>

引入了这个 JS 到需要自适应高度的页面，你的应用就能自动适应高度了。

友情提示：为了对页面性能产生最小的影响，建议此文件放在 </body> 之前

API方法

1、触发行为

1	App.trigger('<cmd>', ['<param>', ['<function>]]);

• <cmd> 必选参数，指定行为的名称
• <param> 可选参数，指定调用行为的参数
• <function> 可选参数，指定行为的异步回调函数

<cmd> 列表如下：

setPageHeight 设置iframe自身的高度 设置页面高度为 500px

1	App.trigger('setPageHeight ', '500');

scrollTo 改变父页面滚动条位置 设置父页面滚动到顶部位置200px的地方

1	App.trigger('scrollTo', 200);

设置父页面滚动到iframe的顶部位置

1	App.trigger('scrollTo', 'page');

parentInfo 获取父页面信息 获取父页面信息

1 2 3 4 5 6 7 8 9 10 11 12 13 14

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.scrollTop 父页面的滚动条scrollTop // parentWin.page.scrollLeft 父页面的滚动条scrollLeft // parentWin.page.url 父页面url // parentWin.win.width 父页面窗口宽度 // parentWin.win.height 父页面窗口高度 });

login 唤起登录浮层 应用支持未登录状态下访问，必要的时候唤起登录浮层来登录微博。 唤起登录浮层

1 2 3 4

App.trigger('login', { // 请注意，redirect_uri 是登录成功后回调的 URL，必须传的是 *.weibo.com 下的 URL，不支持第三方的地址 'redirect_uri' : encodeURIComponent('http://apps.weibo.com/1852339337/8s1i6v74?key=g-16504') });

setTitle 设置父页面标题栏（此API暂未开放） 设置父页面标题栏

1	App.trigger('setTitle', "Home-My Application Name");

2、事件监听 (on/off)

App.on('<event>;', '<function>');
App.off('<event>', '<function>');

• <event>为必选参数，指定要监听的事件称
• <function>为可选参数，指定事件的异步回调函数

<event> 列表如下：

scroll 外层滚动页面的事件 绑定 scroll 事件

1 2 3 4 5

App.on('scroll', function(scrollPos){ console.log(scrollPos); // scrollPos.top 纵向滚动条距顶部距离 // scrollPos.left 横向滚动条距左边框距离 })

解绑 scroll 事件

1	App.off('scroll', <function>)

resize 外层改变页面大小的事件 绑定 resize 事件

1 2 3 4 5 6 7

App.on('resize', function(parentWin) { console.log(parentWin); // parentWin.page.width 父页面宽度 // parentWin.page.height 父页面高度 // parentWin.win.width 父页面窗口宽度 // parentWin.win.height 父页面窗口高度 });

解绑 resize 事件

1	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”

更新日志

• 2014.04.21 parentInfo 返回值增加窗口的尺寸 parentWin.win.width 和 parentWin.win.height
• 2014.04.11 增加调用登录浮层的方法

唤起登录浮层

1 2 3 4

App.trigger('login', { // 请注意，redirect_uri 是登录成功后回调的 URL，必须传的是 *.weibo.com 下的 URL，不支持第三方的地址 'redirect_uri' : encodeURIComponent('http://apps.weibo.com/1852339337/8s1i6v74?key=g-16504') });

联系我们