微信Wi-Fi硬件鉴权协议接口说明

由 如此轻盈 创建，Carrie 最后一次修改 2016-10-08 Wi-Fi硬件鉴权协议接口说明概述硬件鉴权协议主要用于Portal型设备的鉴权方式改造，使设备可以通过识别微信身份给顾客放行，让顾客的手机和PC快速便捷连上Wi-Fi。业务逻辑移动端连Wi-Fi用户连网流程顾客在手机上点选ssid后唤起portal页，点击页面上“微信连Wi-Fi”按钮进入连接前页，展示公众号logo和名称，点击“立即连网”按钮后开始连WiFi，连接成功后跳转到成功连接页，关注商家公众号。模块时序图若无法看清图中文字，可先通过“图片另存为”将图片保存到本地，再放大查看。PC连Wi-Fi用户连网流程顾客在PC上选择ssid后，在浏览器打开portal页，页面上展示连Wi-Fi二维码。用手机微信扫描该二维码，点击手机页面上的“确认”按钮，PC连上Wi-Fi，同时浏览器的portal页自动跳转到商家配置的网页。模块时序图若无法看清图中文字，可先通过“图片另存为”将图片保存到本地，再放大查看。移动端实现流程请按照以下步骤操作，即可完成设备改造，让移动端设备使用微信连Wi-Fi。第一步：获取门店Wi-Fi信息改造portal型设备的第一步，是获得门店Wi-Fi信息，包括：appId，shop_id，ssid，secretkey。有两种获取门店Wi-Fi信息的方法：1. 通过页面操作获得在微信公众平台微信连Wi-Fi插件中，打开【设备管理】->【添加设备】，添加“新增微信方式连网+连网后近场服务”->”Portal型设备”；添加成功后即可获得门店Wi-Fi参数信息。已添加设备也可在【设备详情】->【查看设备改造信息】中，获得门店Wi-Fi参数信息。2. 调用接口获得调用“添加portal型设备”接口获得。第二步：改造移动端portal页面若连网设备是移动设备，在portal页中引用下述微信JSAPI，让原有Wi-Fi portal页具备呼起微信的能力：<script type="text/javascript"    src="https://wifi.weixin.qq.com/resources/js/wechatticket/wechatutil.js" ></script>调用JSAPI触发呼起微信客户端：Wechat_GotoRedirect(appId,      extend,     timestamp, sign,       shop_id,   authUrl,   mac,      ssid );具体示例：Wechat_GotoRedirect('wx23fb4aaf04b8491e',  'demoNew',            '1441768153341',          'a355c78bad9be9235d2105d28f8e010c',   '6747662',  'http://wifi.weixin.qq.com/assistant/wifigw/auth.xhtml?httpCode=200',       'aa:aa:aa:aa:aa:aa',     '2099');参数说明参数是否必须说明appId是商家微信公众平台账号extend是extend里面可以放开发者需要的相关参数集合，最终将透传给运营商认证URL。extend参数只支持英文和数字，且长度不得超过300个字符。timestamp是时间戳使用毫秒sign是请求参数签名，具体计算方法见下方说明shopId是AP设备所在门店的ID，即shop_idauthUrl是认证服务端URL，微信客户端将把用户微信身份信息向此URL提交并获得认证放行mac安卓设备必需用户手机mac地址，格式冒号分隔，字符长度17个，并且字母小写，例如：00:1f:7a:ad:5c:a8ssid是AP设备的无线网络名称签名的计算方法：sign = MD5(appId + extend + timestamp + shopId + authUrl + mac + ssid + secretkey);   注意：这里timestamp为毫秒单位的当前时间戳。第三步：支持临时放行上网请求请确保AP/AC在portal页打开后能够临时放行用户的上网请求。只有临时放行成功，才可以调用上述JSAPI呼起微信，换取用户身份信息，保证后续认证请求顺利完成，从而成功连网。注意：IOS呼起微信时如果网络不通Wi-Fi会被切走，导致连网失败，因此请务必确保AC/AP支持临时放行上网请求。部分安卓设备的web浏览器无法自动呼起微信客户端的问题，请参考常见问题中的解决方案。第四步：接受微信身份认证放行微信客户端被呼起后，将自动向authUrl（JSAPI的传入参数）发起请求，提交认证所需的用户微信身份信息参数，包括extend、openId、tid。微信客户端向authUrl发送请求示例：http://www.foo.com/portal/auth.html?extend=xxx&openId=xxx&tid=xxx参数说明参数说明extend为上文中调用呼起微信JSAPI时传递的extend参数，这里原样回传给商家主页openId用户的微信openIdtid为加密后的用户手机号码（仅作网监部门备案使用）authUrl所对应的后台认证服务器必须能识别这些参数信息，并向微信客户端返回AC认证结果，微信客户端将根据http返回码，提示用户连网成功与否。若http返回码为200，则认为服务认证成功，微信客户端跳转到成功连接页，用户点击“完成”按钮后，将跳转到商家主页；若认证服务器需要转移认证请求，请返回302和下一跳地址，微信客户端将向下一跳地址再发起一次请求，302跳转仅支持一次；对于非200和302，或者超过次数的302返回码，视为认证失败，此次连网失败，微信客户端跳转到连接失败页。注意：微信客户端一次请求的等待时间为10s，请确保后台认证服务器在微信客户端向authUrl发送请求10s之内返回AC认证结果，即http返回码。超过10s未返回认证结果将视为认证失败。第五步：实现扫二维码连网在完成第一至四步的前提下，进行下述配置，可实现portal设备扫二维码连Wi-Fi。具体操作如下：1. 改造portal server跳转内容当一个未认证的手机用户试图联网时，AC会将用户的http请求转跳到Portal Server上的Portal页面，这里AC需要进一步识别，如果这个http请求是来自于微信客户端，则在转跳URL上带上authUrl和extend两个约定参数即可。http://www.foo.com/portal/portal.html?authUrl=http%3A%2F%2Fwww.foo.com%2Fportal%2Fauth.html&extend=xxx参数说明authUrl即第二步portal页中填写的authUrl，是认证服务端URL，微信客户端将把用户微信身份信息向此URL提交并获得认证放行extend为上文中调用呼起微信JSAPI时传递的extend参数，这里原样回传给商家主页2. 如何识别http请求是否来自微信客户端在http数据包的header结构中解析“User-Agent”即可，判断是否包含关键字“micromessenger”（这里请注意不要拦截其他微信http请求，所以关键词请匹配好），示例代码如下：...String userAgent = request.getHeader("User-Agent");if(userAgent.matches(".*micromessenger.*")){  response.sendRedirect("http://www.foo.com/portal/portal.html?authUrl=http%3A%2F%2Fwww.foo.com%2Fportal%2Fauth.html&extend=xxx ");}...微信客户端将解析Portal Server转跳地址中的authUrl和extend参数，继续完成连接流程