Wi-Fi硬體鑑權協定介面說明


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

參數說明

###是商家微信公眾平台帳號extend是
參數是否必須說明
appId
extend裡面可以放開發者需要的相關參數集合，最終將透傳給運營商認證URL。 extend參數只支援英文和數字，長度不得超過300個字元。
timestamp是時間戳記使用毫秒
sign是請求參數簽名，具體計算方法請參考下方說明
shopId是AP裝置所在門市的ID，即shop_id
authUrl是認證服務端URL，微信用戶端將把使用者微信身分資訊向此URL提交並獲得認證放行
mac安卓設備必要用戶手機mac位址，格式冒號分隔，字元長度17個，並且字母小寫，例如：00:1f :7a:ad:5c:a8
ssid#是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用戶的微信openId
tid#為加密後的用戶手機號碼（僅作網監部門備案使用）
#

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參數，繼續完成連接流程。

3. 防止IOS自動彈出portal頁

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

4. 下載物料二維碼

完成portal server改造後，呼叫「取得物料二維碼」接口，下載門市二維碼，張貼於店內，顧客即可掃碼連Wi-Fi。


行動端portal頁範例Demo

#請參考範例Demo，進行行動裝置Portal頁面改造（JS程式碼直接在頁面中）

請用手機瀏覽器開啟以下連結（可手動輸入，也可掃碼取得連結位址）：

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

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


常見問題

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

6.2.5以上的Android版微信已經支援手動開啟用戶端後繼續進行連線流程的功能，為確保此流程順暢進行，開發者需注意以下幾點：

1.保证微信客户端版本为6.2.5以上的Android版微信；
2.参考示例demo中jsapi的写法，在无法自动跳转微信客户端时弹出提示，让用户手动切换到微信；
3.在portal页面中调用微信jsapi时，需保证AP设备的ssid和手机mac这2个参数真实有效；
4.测试过程请从切换到目标ssid动作开始（例如：原来为3G或4G网络然后手动选择目标ssid，原来为非目标ssid的wifi信号然后手动选择目标ssid，等等）。

2. IOS從portal頁面跳到微信後如何保證手機仍保持在目標ssid下？

IOS系統為了確保Wi-Fi是可用的，在用戶選擇完一個ssid後不會馬上切換過去，而是會嗅探通過該ssid是否能觸達公網上的預設服務，如果能嗅到才真正顯示連接該ssid。在彈portal的AP環境中，這點正好被用來彈出portal頁面，如果在portal頁面上完成了認證，則在portal右上方的提示會由“取消”變為“完成”，如果在“取消”狀態下離開這個介面，那麼剛剛選擇的ssid將會被斷開，回到上一個可用的連接，而如果在「完成」狀態下離開這個介面則不會斷開。

由於通過微信認證時，會由portal介面跳到微信，所以確保portal右上角的「完成」狀態是個前提。開發者需要注意以下幾點：

1.确保弹出portal后，临时放行手机的所有流量；
2.临时放行手机的所有流量后，局部或整体刷新portal页面触发IOS再次进行嗅探；
3.IOS嗅探可以正常触达公网上的预设服务后“取消”变为“完成”；
4.以上动作完成后，再调用跳转微信的JSAPI，继而跳转微信完成认证连接流程。


PC端實作流程

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

第一步：取得門市Wi-Fi資訊

實作PC連Wi-Fi的第一步，是獲得門市Wi-Fi訊息，包括：appId，shop_id。有兩種取得門市Wi-Fi資訊的方法：

##1. 頁面操作獲得

在

微信公眾平台開通微信連Wi- Fi插件，在【設備管理】->【新增設備】裡，新增「新增微信方式連網連網後近場服務」->」Portal型設備」；增加成功後即可獲得門市Wi- Fi參數資訊。

已新增設備也可在【設備詳情】->【查看設備改造資訊】中，取得門市Wi-Fi參數資訊。

2. 透過介面取得

呼叫「取得WiFi門市清單」介面取得shop_id，也就是裝置要加入的門市的ID。

第二步：改造PC端portal頁

#若連網裝置為PC，在portal頁中引用下述微信JSAPI，讓原有的Wi-Fi portal頁具備呼起微信的能力：

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

呼叫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>

參數說明

###是二維碼圖片放置位置appId是商家微信公眾平台帳號shopId是即shop_id，裝置所在門市的ID（微信大眾平台門市）extend#是authUrl是認證服務端URL，微信用戶端將把使用者微信身分資訊向此URL提交並取得認證放行


步驟三：支援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

第四步：支援行動端暫時放行上網請求

請參考行動裝置實作流程的第三步，支援行動端臨時放行上網請求。

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

請參考行動端實作流程的第四步，接受微信身份認證並放行。

PC端portal頁範例Demo

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

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



離線認證方式

Wi-Fi環境無法做到臨時放行用戶流量用於與微信後台通信，可採用離線認證方式實現。請依照以下步驟操作，即可在行動端使用微信連Wi-Fi。


模組時序圖

#  若無法看清圖中文字，可先透過「圖片另存為」將圖片儲存到本機，再放大檢視



#

第一步：取得門市Wi-Fi資訊

請參考行動裝置實作流程的第一步，取得門市的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;
}

參數說明


參數是否必須說明
#target
extend裡面可以放開發者所需的相關參數集合，最後將透傳給運營商認證URL。 extend參數只支援英文和數字，長度不得超過300個字元。
##是商家微信公眾平台帳號shopId是即shop_id，裝置所在門市的ID（微信大眾平台門市）authUrl是認證服務端URL，微信用戶端將把使用者微信身分資訊向此URL提交並獲得認證放行。 extend是
參數是否必須說明
appId
authUrl的值是經過Url編碼的，如：http://192.168.1.1/auth.html?t=abc&s=123
extend裡面可以放開發者需要的相關參數集合，最後將透傳給運營商認證URL。 extend參數只支援英文和數字，長度不得超過300個字元。
timestamp是時間戳記使用毫秒
sign是請求參數簽名，具體計算方法請參考下方說明


簽署的計算方法：

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發起認證請求，提交extend參數。使用者微信身分（tid參數）將透過商家主頁傳遞，請開發者註意在商家主頁的後台取得。微信客戶端向authUrl發送請求範例：

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

參數說明

#
參數說明
#extend為上文中呼叫呼起微信JSAPI時傳遞的extend參數，這裡原樣回傳給商家主頁

authUrl所對應的後台認證伺服器必須能識別這些參數信息，並向微信客戶端返回AC認證結果，微信用戶端會依http回傳碼，提示用戶連網成功與否。

若http回傳碼為200，則認為服務認證成功，微信用戶端跳到成功連線頁，使用者點選「完成」按鈕後，將跳到商家首頁；若認證伺服器需要轉移認證請求，請返回302和下一跳地址，微信客戶端將向下一跳地址再發起一次請求，302跳轉僅支援一次；對於非200和302，或者超過次數的302返回碼，視為認證失敗，此次連網失敗，微信客戶端跳到連線失敗頁。

注意：微信客戶端一次要求的等待時間為10s，請確保後台認證伺服器在微信客戶端向authUrl發送請求10s之內回傳AC認證結果，即http回傳碼。超過10s未回傳認證結果將視為認證失敗。