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

概述

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

業(yè)務邏輯

移動端連Wi-Fi

用戶連網(wǎng)流程

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

模塊時序圖

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

PC連Wi-Fi

用戶連網(wǎng)流程

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

模塊時序圖

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

移動端實現(xiàn)流程

請按照以下步驟操作，即可完成設備改造，讓移動端設備使用微信連Wi-Fi。

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

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

1. 通過頁面操作獲得

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

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

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

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

第二步：改造移動端portal頁面

若連網(wǎng)設備是移動設備，在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ù)說明

簽名的計算方法：

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

   注意：這里timestamp為毫秒單位的當前時間戳。

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

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

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

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

第四步：接受微信身份認證放行

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

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

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

參數(shù)說明

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

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

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

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

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

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

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

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

2. 如何識別http請求是否來自微信客戶端

在http數(shù)據(jù)包的header結(jié)構中解析“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轉(zhuǎn)跳地址中的authUrl和extend參數(shù)，繼續(xù)完成連接流程。

3. 防止IOS自動彈出portal頁

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

4. 下載物料二維碼

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

移動端portal頁示例Demo

請參考示例Demo，進行移動端Portal頁面改造（JS代碼直接在頁面中）

請用手機瀏覽器打開以下鏈接（可手動輸入，也可掃碼獲得鏈接地址）：

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

如果用微信掃碼，請點擊有右上角按鈕，選擇“在瀏覽器中打開”頁面，不要直接在微信瀏覽器中體驗。

常見問題

1. 部分安卓手機的web瀏覽器無法自動呼起微信客戶端

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

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

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

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

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

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

PC端實現(xiàn)流程

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

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

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

1. 頁面操作獲得

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

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

2. 通過接口獲得

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

第二步：改造PC端portal頁

若連網(wǎng)設備為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須對PC做白名單放行，以支持portal頁面引用jsapi，以及輪詢微信后臺并獲取openid和tid。

請對微信連Wi-Fi的URL做白名單支持，URL為：

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

以支持：

1.引用jsapi：

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

2.輪詢微信后臺獲取openid和tid：

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

第四步：支持移動端臨時放行上網(wǎng)請求

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

第五步：接受微信身份認證放行

請參考移動端實現(xiàn)流程的第四步，接受微信身份認證并放行。

PC端portal頁示例Demo

請參考示例Demo，進行PC端Portal頁面改造（JS代碼直接在頁面中）：

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

離線認證方式

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

模塊時序圖

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

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

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

第二步：改造移動端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ù)說明

簽名的計算方法：

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

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

第三步：支持微信身份認證放行

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

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

參數(shù)說明

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

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

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