微信Wi-Fi硬件鑒權(quán)協(xié)議接口說明

概述

硬件鑒權(quán)協(xié)議主要用于Portal型設(shè)備的鑒權(quán)方式改造，使設(shè)備可以通過識(shí)別微信身份給顧客放行，讓顧客的手機(jī)和PC快速便捷連上Wi-Fi。

業(yè)務(wù)邏輯

移動(dòng)端連Wi-Fi

用戶連網(wǎng)流程

顧客在手機(jī)上點(diǎn)選ssid后喚起portal頁，點(diǎn)擊頁面上“微信連Wi-Fi”按鈕進(jìn)入連接前頁，展示公眾號(hào)logo和名稱，點(diǎn)擊“立即連網(wǎng)”按鈕后開始連WiFi，連接成功后跳轉(zhuǎn)到成功連接頁，關(guān)注商家公眾號(hào)。

模塊時(shí)序圖

若無法看清圖中文字，可先通過“圖片另存為”將圖片保存到本地，再放大查看。

PC連Wi-Fi

用戶連網(wǎng)流程

顧客在PC上選擇ssid后，在瀏覽器打開portal頁，頁面上展示連Wi-Fi二維碼。用手機(jī)微信掃描該二維碼，點(diǎn)擊手機(jī)頁面上的“確認(rèn)”按鈕，PC連上Wi-Fi，同時(shí)瀏覽器的portal頁自動(dòng)跳轉(zhuǎn)到商家配置的網(wǎng)頁。

模塊時(shí)序圖

若無法看清圖中文字，可先通過“圖片另存為”將圖片保存到本地，再放大查看。

移動(dòng)端實(shí)現(xiàn)流程

請(qǐng)按照以下步驟操作，即可完成設(shè)備改造，讓移動(dòng)端設(shè)備使用微信連Wi-Fi。

第一步：獲取門店Wi-Fi信息

改造portal型設(shè)備的第一步，是獲得門店Wi-Fi信息，包括：appId，shop_id，ssid，secretkey。有兩種獲取門店Wi-Fi信息的方法：

1. 通過頁面操作獲得

在微信公眾平臺(tái)微信連Wi-Fi插件中，打開【設(shè)備管理】->【添加設(shè)備】，添加“新增微信方式連網(wǎng)+連網(wǎng)后近場(chǎng)服務(wù)”->”Portal型設(shè)備”；添加成功后即可獲得門店Wi-Fi參數(shù)信息。

已添加設(shè)備也可在【設(shè)備詳情】->【查看設(shè)備改造信息】中，獲得門店Wi-Fi參數(shù)信息。

2. 調(diào)用接口獲得

調(diào)用“添加portal型設(shè)備”接口獲得。

第二步：改造移動(dòng)端portal頁面

若連網(wǎng)設(shè)備是移動(dòng)設(shè)備，在portal頁中引用下述微信JSAPI，讓原有Wi-Fi portal頁具備呼起微信的能力：

<script type="text/javascript"    
src="https://wifi.weixin.qq.com/resources/js/wechatticket/wechatutil.js" rel="external nofollow"  ></script>

調(diào)用JSAPI觸發(fā)呼起微信客戶端：

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');

參數(shù)說明

簽名的計(jì)算方法：

sign = MD5(appId + extend + timestamp + shopId + authUrl + mac + ssid + secretkey);

   注意：這里timestamp為毫秒單位的當(dāng)前時(shí)間戳。

第三步：支持臨時(shí)放行上網(wǎng)請(qǐng)求

請(qǐng)確保AP/AC在portal頁打開后能夠臨時(shí)放行用戶的上網(wǎng)請(qǐng)求。只有臨時(shí)放行成功，才可以調(diào)用上述JSAPI呼起微信，換取用戶身份信息，保證后續(xù)認(rèn)證請(qǐng)求順利完成，從而成功連網(wǎng)。

注意：IOS呼起微信時(shí)如果網(wǎng)絡(luò)不通Wi-Fi會(huì)被切走，導(dǎo)致連網(wǎng)失敗，因此請(qǐng)務(wù)必確保AC/AP支持臨時(shí)放行上網(wǎng)請(qǐng)求。

部分安卓設(shè)備的web瀏覽器無法自動(dòng)呼起微信客戶端的問題，請(qǐng)參考常見問題中的解決方案。

第四步：接受微信身份認(rèn)證放行

微信客戶端被呼起后，將自動(dòng)向authUrl（JSAPI的傳入?yún)?shù)）發(fā)起請(qǐng)求，提交認(rèn)證所需的用戶微信身份信息參數(shù)，包括extend、openId、tid。

微信客戶端向authUrl發(fā)送請(qǐng)求示例：

http://www.foo.com/portal/auth.html?extend=xxx&openId=xxx&tid=xxx

參數(shù)說明

authUrl所對(duì)應(yīng)的后臺(tái)認(rèn)證服務(wù)器必須能識(shí)別這些參數(shù)信息，并向微信客戶端返回AC認(rèn)證結(jié)果，微信客戶端將根據(jù)http返回碼，提示用戶連網(wǎng)成功與否。

若http返回碼為200，則認(rèn)為服務(wù)認(rèn)證成功，微信客戶端跳轉(zhuǎn)到成功連接頁，用戶點(diǎn)擊“完成”按鈕后，將跳轉(zhuǎn)到商家主頁；若認(rèn)證服務(wù)器需要轉(zhuǎn)移認(rèn)證請(qǐng)求，請(qǐng)返回302和下一跳地址，微信客戶端將向下一跳地址再發(fā)起一次請(qǐng)求，302跳轉(zhuǎn)僅支持一次；對(duì)于非200和302，或者超過次數(shù)的302返回碼，視為認(rèn)證失敗，此次連網(wǎng)失敗，微信客戶端跳轉(zhuǎn)到連接失敗頁。

注意：微信客戶端一次請(qǐng)求的等待時(shí)間為10s，請(qǐng)確保后臺(tái)認(rèn)證服務(wù)器在微信客戶端向authUrl發(fā)送請(qǐng)求10s之內(nèi)返回AC認(rèn)證結(jié)果，即http返回碼。超過10s未返回認(rèn)證結(jié)果將視為認(rèn)證失敗。

第五步：實(shí)現(xiàn)掃二維碼連網(wǎng)

在完成第一至四步的前提下，進(jìn)行下述配置，可實(shí)現(xiàn)portal設(shè)備掃二維碼連Wi-Fi。具體操作如下：

1. 改造portal server跳轉(zhuǎn)內(nèi)容

當(dāng)一個(gè)未認(rèn)證的手機(jī)用戶試圖聯(lián)網(wǎng)時(shí)，AC會(huì)將用戶的http請(qǐng)求轉(zhuǎn)跳到Portal Server上的Portal頁面，這里AC需要進(jìn)一步識(shí)別，如果這個(gè)http請(qǐng)求是來自于微信客戶端，則在轉(zhuǎn)跳URL上帶上authUrl和extend兩個(gè)約定參數(shù)即可。

http://www.foo.com/portal/portal.html?authUrl=http%3A%2F%2Fwww.foo.com%2Fportal%2Fauth.html&extend=xxx

2. 如何識(shí)別http請(qǐng)求是否來自微信客戶端

在http數(shù)據(jù)包的header結(jié)構(gòu)中解析“User-Agent”即可，判斷是否包含關(guān)鍵字“micromessenger”（這里請(qǐng)注意不要攔截其他微信http請(qǐng)求，所以關(guān)鍵詞請(qǐng)匹配好），示例代碼如下：

...
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轉(zhuǎn)跳地址中的authUrl和extend參數(shù)，繼續(xù)完成連接流程。

3. 防止IOS自動(dòng)彈出portal頁

為了防止IOS切換ssid時(shí)自動(dòng)彈出portal頁，請(qǐng)將IOS的嗅探地址“http://captive.apple.com/hotspot-detect.html”放入白名單。

4. 下載物料二維碼

完成portal server改造后，調(diào)用“獲取物料二維碼”接口，下載該門店二維碼，張貼于店內(nèi)，顧客即可掃碼連Wi-Fi。

移動(dòng)端portal頁示例Demo

請(qǐng)參考示例Demo，進(jìn)行移動(dòng)端Portal頁面改造（JS代碼直接在頁面中）

請(qǐng)用手機(jī)瀏覽器打開以下鏈接（可手動(dòng)輸入，也可掃碼獲得鏈接地址）：

https://wifi.weixin.qq.com/operator/demoNew.xhtml

如果用微信掃碼，請(qǐng)點(diǎn)擊有右上角按鈕，選擇“在瀏覽器中打開”頁面，不要直接在微信瀏覽器中體驗(yàn)。

常見問題

1. 部分安卓手機(jī)的web瀏覽器無法自動(dòng)呼起微信客戶端

6.2.5以上的Android版微信已經(jīng)支持手動(dòng)打開客戶端后繼續(xù)進(jìn)行連接流程的功能，為保證此流程順暢進(jìn)行，開發(fā)者需注意以下幾點(diǎn)：

1.保證微信客戶端版本為6.2.5以上的Android版微信；
2.參考示例demo中jsapi的寫法，在無法自動(dòng)跳轉(zhuǎn)微信客戶端時(shí)彈出提示，讓用戶手動(dòng)切換到微信；
3.在portal頁面中調(diào)用微信jsapi時(shí)，需保證AP設(shè)備的ssid和手機(jī)mac這2個(gè)參數(shù)真實(shí)有效；
4.測(cè)試過程請(qǐng)從切換到目標(biāo)ssid動(dòng)作開始（例如：原來為3G或4G網(wǎng)絡(luò)然后手動(dòng)選擇目標(biāo)ssid，原來為非目標(biāo)ssid的wifi信號(hào)然后手動(dòng)選擇目標(biāo)ssid，等等）。

2. IOS從portal頁面跳轉(zhuǎn)到微信后如何保證手機(jī)仍保持在目標(biāo)ssid下？

IOS系統(tǒng)為了保證Wi-Fi是可用的，在用戶選擇完一個(gè)ssid后不會(huì)馬上切換過去，而是會(huì)嗅探通過該ssid是否能觸達(dá)公網(wǎng)上的預(yù)設(shè)服務(wù)，如果能嗅探到才真正顯示連接該ssid。在彈portal的AP環(huán)境中，這點(diǎn)正好被用來彈出portal頁面，如果在portal頁面上完成了認(rèn)證，則在portal右上方的提示會(huì)由“取消”變?yōu)椤巴瓿伞?，如果在“取消”狀態(tài)下離開這個(gè)界面，那么剛剛選擇的ssid將會(huì)被斷開，回到上一個(gè)可用的連接，而如果在“完成”狀態(tài)下離開這個(gè)界面則不會(huì)斷開。

由于通過微信認(rèn)證時(shí)，會(huì)由portal界面跳轉(zhuǎn)到微信，所以確保portal右上角的“完成”狀態(tài)是個(gè)前提。開發(fā)者需要注意以下幾點(diǎn)：

1.確保彈出portal后，臨時(shí)放行手機(jī)的所有流量；
2.臨時(shí)放行手機(jī)的所有流量后，局部或整體刷新portal頁面觸發(fā)IOS再次進(jìn)行嗅探；
3.IOS嗅探可以正常觸達(dá)公網(wǎng)上的預(yù)設(shè)服務(wù)后“取消”變?yōu)椤巴瓿伞保?4.以上動(dòng)作完成后，再調(diào)用跳轉(zhuǎn)微信的JSAPI，繼而跳轉(zhuǎn)微信完成認(rèn)證連接流程。

PC端實(shí)現(xiàn)流程

請(qǐng)按照以下步驟操作，即可在PC端使用微信連Wi-Fi。

第一步：獲取門店Wi-Fi信息

實(shí)現(xiàn)PC連Wi-Fi的第一步，是獲得門店Wi-Fi信息，包括：appId，shop_id。有兩種獲取門店Wi-Fi信息的方法：

1. 頁面操作獲得

在微信公眾平臺(tái)開通微信連Wi-Fi插件，在【設(shè)備管理】->【添加設(shè)備】里，添加“新增微信方式連網(wǎng)+連網(wǎng)后近場(chǎng)服務(wù)”->”Portal型設(shè)備”；添加成功后即可獲得門店Wi-Fi參數(shù)信息。

已添加設(shè)備也可在【設(shè)備詳情】->【查看設(shè)備改造信息】中，獲得門店Wi-Fi參數(shù)信息。

2. 通過接口獲得

調(diào)用“獲取WiFi門店列表”接口獲得shop_id，即設(shè)備要添加到的門店的ID。

第二步：改造PC端portal頁

若連網(wǎng)設(shè)備為PC，在portal頁中引用下述微信JSAPI，讓原有的Wi-Fi portal頁具備呼起微信的能力：

<script type="text/javascript"    
src="https://wifi.weixin.qq.com/resources/js/wechatticket/pcauth.js" rel="external nofollow"  ></script>

調(diào)用JSAPI生成二維碼，具體示例代碼如下：

 <script type="text/javascript">
	    JSAPI.auth({
	    	target : document.getElementById('qrcode_zone'),
	        appId : 'wx23fb4aaf04b8491e',
	        shopId : 6747662,
	        extend : 'wechatpc',
	        authUrl : 'http://wximg.qq.com/tmt/wifi-landing-pc/dist/html/index-success.html'
	    });
</script>

參數(shù)說明

第三步：支持PC端白名單放行

AP/AC須對(duì)PC做白名單放行，以支持portal頁面引用jsapi，以及輪詢微信后臺(tái)并獲取openid和tid。

請(qǐng)對(duì)微信連Wi-Fi的URL做白名單支持，URL為：

https://wifi.weixin.qq.com/

以支持：

1.引用jsapi：

https://wifi.weixin.qq.com/resources/js/wechatticket/pcauth.js

2.輪詢微信后臺(tái)獲取openid和tid：

https://wifi.weixin.qq.com/cgi-bin/pollpcresult

第四步：支持移動(dòng)端臨時(shí)放行上網(wǎng)請(qǐng)求

請(qǐng)參考移動(dòng)端實(shí)現(xiàn)流程的第三步，支持移動(dòng)端臨時(shí)放行上網(wǎng)請(qǐng)求。

第五步：接受微信身份認(rèn)證放行

請(qǐng)參考移動(dòng)端實(shí)現(xiàn)流程的第四步，接受微信身份認(rèn)證并放行。

PC端portal頁示例Demo

請(qǐng)參考示例Demo，進(jìn)行PC端Portal頁面改造（JS代碼直接在頁面中）：

https://wifi.weixin.qq.com/operator/demoForPc.xhtml

離線認(rèn)證方式

Wi-Fi環(huán)境無法做到臨時(shí)放行用戶流量用于與微信后臺(tái)通信，可采用離線認(rèn)證方式實(shí)現(xiàn)。請(qǐng)按照以下步驟操作，即可在移動(dòng)端使用微信連Wi-Fi。

模塊時(shí)序圖

  若無法看清圖中文字，可先通過“圖片另存為”將圖片保存到本地，再放大查看

第一步：獲取門店Wi-Fi信息

請(qǐng)參考移動(dòng)端實(shí)現(xiàn)流程的第一步，獲取門店的Wi-Fi信息。

第二步：改造移動(dòng)端portal頁

在portal頁中引用離線呼起微信的鏈接，讓原有的Wi-Fi的portal頁具備呼起微信客戶端的能力。鏈接格式具體如下：

 function callWechatBrowser(){
	var appId = getParam('appId');
	var shopId = getParam('shopId');
	var authUrl = getParam('authUrl');
	var extend = getParam('extend');
	var timestamp = getParam('timestamp');
	var sign = getParam('sign');
	var weixinUrl = 'weixin://connectToFreeWifi/?apKey=_p33beta&appId='+appId+'&shopId='+shopId+'&authUrl='+authUrl+'&extend='+extend+'&timestamp='+timestamp+'&sign='+sign;	
	window.location=weixinUrl;
}

參數(shù)說明

簽名的計(jì)算方法：

sign = MD5(appId + extend + timestamp + shop_id + authUrl + mac + ssid + secretkey);

   注意：這里timestamp為毫秒單位的當(dāng)前時(shí)間戳。authUrl在簽名時(shí)為未編碼的url格式，如：http://192.168.1.1/auth.html?t=abc&s=123 

第三步：支持微信身份認(rèn)證放行

微信客戶端被呼起后，將自動(dòng)向authUrl發(fā)起認(rèn)證請(qǐng)求，提交extend參數(shù)。用戶微信身份（tid參數(shù)）將通過商戶主頁傳遞，請(qǐng)開發(fā)者注意在商家主頁的后臺(tái)獲取。 微信客戶端向authUrl發(fā)送請(qǐng)求示例：

http://www.foo.com/portal/auth.html?extend=xxx

參數(shù)說明

authUrl所對(duì)應(yīng)的后臺(tái)認(rèn)證服務(wù)器必須能識(shí)別這些參數(shù)信息，并向微信客戶端返回AC認(rèn)證結(jié)果，微信客戶端將根據(jù)http返回碼，提示用戶連網(wǎng)成功與否。

若http返回碼為200，則認(rèn)為服務(wù)認(rèn)證成功，微信客戶端跳轉(zhuǎn)到成功連接頁，用戶點(diǎn)擊“完成”按鈕后，將跳轉(zhuǎn)到商家主頁；若認(rèn)證服務(wù)器需要轉(zhuǎn)移認(rèn)證請(qǐng)求，請(qǐng)返回302和下一跳地址，微信客戶端將向下一跳地址再發(fā)起一次請(qǐng)求，302跳轉(zhuǎn)僅支持一次；對(duì)于非200和302，或者超過次數(shù)的302返回碼，視為認(rèn)證失敗，此次連網(wǎng)失敗，微信客戶端跳轉(zhuǎn)到連接失敗頁。

注意：微信客戶端一次請(qǐng)求的等待時(shí)間為10s，請(qǐng)確保后臺(tái)認(rèn)證服務(wù)器在微信客戶端向authUrl發(fā)送請(qǐng)求10s之內(nèi)返回AC認(rèn)證結(jié)果，即http返回碼。超過10s未返回認(rèn)證結(jié)果將視為認(rèn)證失敗。