微信5.0發布
2013年8月5日,伴隨著微信5.0 iPhone版的發布,公眾平台也進行了重要的更新,主要包括:
1)運營主體為組織,可選擇成為服務號或者訂閱號;
2)服務號可以申請自定義菜單;
3)使用QQ登錄的公眾號,可以升級為郵箱登錄;
4)使用郵箱登錄的公眾號,可以修改登錄郵箱;
5)編輯圖文消息可選填作者;
6)群發消息可以同步到騰訊微博。
其中,大家議論最多的當屬前兩條,就是關於帳號類型和自定義菜單的更新,我這裡做幾點補充說明:
1)目前公眾號類型分為兩種:服務號和訂閱號,8月5日平台更新後所有的帳號默認為訂閱號,有一次轉換成服務號的機會;
2)服務號主要面向企業、政府和其他組織,而訂閱號主要面向媒體和個人;
3)只有服務號可以申請自定義菜單,訂閱號不能申請;
4)服務號每月只能群發一條消息,而訂閱號每天能群發一條消息。
平台更新後,讓很多人糾結的是自定義菜單和每天群發一條消息不可兼得,對此,我不想過多評論。
引言及內容概要
在微信5.0以前,自定義菜單是作為一種內測資格使用的,只有少數公眾帳號擁有菜單,因此出現很多企業為了弄到菜單不惜重金求購。現如今,一大批帳號從訂閱號轉為服務號,很多都是奔著自定義菜單去的。而且,經測試發現,微信最近的審核放松很多,只要申請服務號、自定義菜單的基本都成功了,根本不管填寫的資料真偽。不知道以後微信會不會翻臉,要求補全企業資料,那將會是一種給小孩一顆糖吃再把他打哭的感覺。。。
自定義菜單是申請到了,到底該怎麼創建、怎麼使用呢?最近幾天不管是微信官方交流群,還是在我博客留言裡,都能夠看到不少開發者都在為這個發愁。本篇文章就為大家解決這個難題。
自定義菜單的創建步驟
1、找到AppId和AppSecret。自定義菜單申請成功後,在“高級功能”-“開發模式”-“接口配置信息”的最後兩項就是;
2、根據AppId和AppSecret,以https get方式獲取訪問特殊接口所必須的憑證access_token;
3、根據access_token,將json格式的菜單數據通過https post方式提交。
分析創建菜單的難點
原來創建菜單這麼簡單,三步就能搞定?跟把大象放冰箱差不多。呵呵,當然沒有這麼簡單,那我們一步步來看,到底難在哪裡?
首先,第1步肯定都沒有問題,只要成功申請了自定義菜單,一定能拿到AppId和AppSecret這兩個值。
再來看第2步,由於是get方式獲取access_token,很多人直接把拼好的url放在浏覽器裡執行,access_token就拿到了。拋開是不是用編程方式實現的來說,這真是個好辦法,顯然大家在第二步上也沒有問題。
最後再看第3步,拼裝json格式的菜單數據,雖然繁鎖一點,但基本上也都沒有什麼問題的,因為官方給了個例子,照貓畫虎就行了。那問題一定就出現在https post提交上了。
結論:不知道如何創建自定義菜單的朋友,大都可以歸為以下三種情況:
1)根本不看或者沒看懂公眾平台API文檔中關於“通用接口”、“自定義菜單接口”和“使用限制”部分的說明;
2)不知道如何發起HTTPS請求(平時的http請求,直接使用HttpUrlConnection就可以輕松搞定,但https請求要復雜一點);
3)不知道如何通過POST方式提交json格式的菜單數據。
正在看文章的你,不知道是屬於哪一種,或者幾種情況都有,不妨留言說出來,也可以做個調查。不管屬於哪一種情況,既然看到了這篇文章,相信一定會讓你弄明白的。
解讀通用接口文檔---憑證的獲取
我們先來看通用接口文檔的簡介部分,如下圖所示。
通俗點講,這段簡介可以這麼理解:公眾平台還有很多特殊的接口,像自定義菜單的創建、語音文件的獲取、主動發送消息等,如果開發者想通過HTTP請求訪問這些特殊接口,就必須要有訪問憑證,也就是access_token。
那麼,又該如何獲取接口訪問憑證access_token呢?讓我們繼續往下看。
圖中已經表達的很清楚了,獲取access_token是通過GET方式訪問如下鏈接:
https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET
鏈接中有三個參數,分別是grant_type、appid和secret。根據圖中的參數說明,grant_type傳固定值client_credential,而appid和secret就是申請完自定義菜單後微信分配給我們的。
請求發送成功後,微信服務器會返回一個json串,包含access_token和expires_in兩個元素。其中,access_token就是我們最終需要的憑證,而expires_in是憑證的有效期,單位是秒,7200秒也就是2個小時。這就意味著,不是每次訪問特殊接口,都需要重新獲取一次access_token,只要access_token還在有效期內,就一直可以使用。
解讀自定義菜單接口文檔
還是一樣,先來看看自定義菜單接口的簡介部分,如下圖所示。
從圖中我們能夠獲取到以下信息:
1)拿到憑證access_token後,我們能對菜單執行三種操作:創建、查詢和刪除;
2)自定義菜單目前只支持click一種事件,即用戶點擊後回復某種類型的消息;不能夠實現點擊菜單項直接打開頁面(type=view未開放,目前只是微生活有);
3)由於微信客戶端緩存的原因,菜單創建後並不會立即在微信上顯示出來,需要過24小時。在測試菜單創建時,可以通過取消關注後,再關注的方式達到立即看菜單的目的。
繼續往下看,就是關於菜單怎麼創建的介紹了,如下圖所示。
其實就是向地址https://api.weixin.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN以POST方式提交一個JSON格式的菜單字符串。
後面,關於參數說明的部分我就不一一貼圖說明了,把重點說一下:
1)自定義菜單是一個3x5結構的,即菜單最多只能有二級,一級菜單最多只能有3個,每個一級菜單下最多可以有5個二級菜單項;
2)菜單項都有一個key值。當用戶點擊某個菜單項時,微信會將該菜單項的key值以事件推送的方式發送給我們的後台處理程序。
關於菜單的查詢、創建我就不提了,這兩個接口使用的頻率非常小,一般都用不上。如果需要,再按照我上面提供的思路也不難理解。
解讀API文檔之使用限制
很多小伙伴看到這張圖就開始疑惑了:怎麼菜單還限制使用次數,用戶量越來越大的時候,根本不夠用啊。看清楚,這個限制是針對接口調用的,也就是針對開發者的,和用戶數、使用次數半點關系也沒有。
就先拿獲取憑證接口來說吧,限制一天只能調用200次。還記得前面提到過access_token是有有效期的,並且有效期為兩小時,也就是獲取一次access_token後的兩小時內,都可以繼續使用,那麼理想情況一天24小時內,是不是只需要獲取12次就夠了?難道200次還不夠用?
再來看下菜單創建接口限制一天只能調用100次。我就這麼解釋吧,菜單創建一次後,只要你不切換模式(指的是在編輯模式和開發模式間切換)、不調用刪除接口,這個菜單會永遠存在的。誰沒事干,一天要創建100次菜單,就算是測試,測個10次8次足夠了吧?
菜單的查詢和刪除接口的限制我就不解釋了,至今為止這二個接口我都沒使用過一次。就算有這樣的使用需求,一天這麼多次的調用,完全足夠了。
封裝通用的請求方法
讀到這裡,就默認大家已經掌握了上面講到的所有關於自定義菜單的理論知識,下面就進入代碼實戰講解的部分。
先前我們了解到,創建菜單需要調用二個接口,並且都是https請求,而非http。如果要封裝一個通用的請求方法,該方法至少需要具備以下能力:
1)支持HTTPS請求;
2)支持GET、POST兩種方式;
3)支持參數提交,也支持無參數的情況;
對於https請求,我們需要一個證書信任管理器,這個管理器類需要自己定義,但需要實現X509TrustManager接口,代碼如下:
package org.liufeng.weixin.util; import java.security.cert.CertificateException; import java.security.cert.X509Certificate; import javax.net.ssl.X509TrustManager; /** * 證書信任管理器(用於https請求) * * @author liufeng * @date 2013-08-08 */ public class MyX509TrustManager implements X509TrustManager { public void checkClientTrusted(X509Certificate[] chain, String authType) throws CertificateException { } public void checkServerTrusted(X509Certificate[] chain, String authType) throws CertificateException { } public X509Certificate[] getAcceptedIssuers() { return null; } }
這個證書管理器的作用就是讓它信任我們指定的證書,上面的代碼意味著信任所有證書,不管是否權威機構頒發。
證書有了,通用的https請求方法就不難實現了,實現代碼如下:
package org.liufeng.weixin.util; import java.io.BufferedReader; import java.io.InputStream; import java.io.InputStreamReader; import java.io.OutputStream; import java.net.ConnectException; import java.net.URL; import javax.net.ssl.HttpsURLConnection; import javax.net.ssl.SSLContext; import javax.net.ssl.SSLSocketFactory; import javax.net.ssl.TrustManager; import net.sf.json.JSONObject; import org.slf4j.Logger; import org.slf4j.LoggerFactory; /** * 公眾平台通用接口工具類 * * @author liuyq * @date 2013-08-09 */ public class WeixinUtil { private static Logger log = LoggerFactory.getLogger(WeixinUtil.class); /** * 發起https請求並獲取結果 * * @param requestUrl 請求地址 * @param requestMethod 請求方式(GET、POST) * @param outputStr 提交的數據 * @return JSONObject(通過JSONObject.get(key)的方式獲取json對象的屬性值) */ public static JSONObject httpRequest(String requestUrl, String requestMethod, String outputStr) { JSONObject jsonObject = null; StringBuffer buffer = new StringBuffer(); try { // 創建SSLContext對象,並使用我們指定的信任管理器初始化 TrustManager[] tm = { new MyX509TrustManager() }; SSLContext sslContext = SSLContext.getInstance("SSL", "SunJSSE"); sslContext.init(null, tm, new java.security.SecureRandom()); // 從上述SSLContext對象中得到SSLSocketFactory對象 SSLSocketFactory ssf = sslContext.getSocketFactory(); URL url = new URL(requestUrl); HttpsURLConnection httpUrlConn = (HttpsURLConnection) url.openConnection(); httpUrlConn.setSSLSocketFactory(ssf); httpUrlConn.setDoOutput(true); httpUrlConn.setDoInput(true); httpUrlConn.setUseCaches(false); // 設置請求方式(GET/POST) httpUrlConn.setRequestMethod(requestMethod); if ("GET".equalsIgnoreCase(requestMethod)) httpUrlConn.connect(); // 當有數據需要提交時 if (null != outputStr) { OutputStream outputStream = httpUrlConn.getOutputStream(); // 注意編碼格式,防止中文亂碼 outputStream.write(outputStr.getBytes("UTF-8")); outputStream.close(); } // 將返回的輸入流轉換成字符串 InputStream inputStream = httpUrlConn.getInputStream(); InputStreamReader inputStreamReader = new InputStreamReader(inputStream, "utf-8"); BufferedReader bufferedReader = new BufferedReader(inputStreamReader); String str = null; while ((str = bufferedReader.readLine()) != null) { buffer.append(str); } bufferedReader.close(); inputStreamReader.close(); // 釋放資源 inputStream.close(); inputStream = null; httpUrlConn.disconnect(); jsonObject = JSONObject.fromObject(buffer.toString()); } catch (ConnectException ce) { log.error("Weixin server connection timed out."); } catch (Exception e) { log.error("https request error:{}", e); } return jsonObject; } }
代碼說明:
1)41~50行:解決https請求的問題,很多人問題就出在這裡;
2)55~59行:兼容GET、POST兩種方式;
3)61~67行:兼容有數據提交、無數據提交兩種情況,也有相當一部分人不知道如何POST提交數據;
Pojo類的封裝
在獲取憑證創建菜單前,我們還需要封裝一些pojo,這會讓我們的代碼更美觀,有條理。
首先是調用獲取憑證接口後,微信服務器會返回json格式的數據:{"access_token":"ACCESS_TOKEN","expires_in":7200},我們將其封裝為一個AccessToken對象,對象有二個屬性:token和expiresIn,代碼如下:
package org.liufeng.weixin.pojo; /** * 微信通用接口憑證 * * @author liufeng * @date 2013-08-08 */ public class AccessToken { // 獲取到的憑證 private String token; // 憑證有效時間,單位:秒 private int expiresIn; public String getToken() { return token; } public void setToken(String token) { this.token = token; } public int getExpiresIn() { return expiresIn; } public void setExpiresIn(int expiresIn) { this.expiresIn = expiresIn; } }接下來是對菜單結構的封裝。因為我們是采用面向對象的編程方式,最終提交的json格式菜單數據就應該是由對象直接轉換得到,而不是在程序代碼中拼一大堆json數據。菜單結構封裝的依據是公眾平台API文檔中給出的那一段json格式的菜單結構,如下所示:
{ "button":[ { "type":"click", "name":"今日歌曲", "key":"V1001_TODAY_MUSIC" }, { "type":"click", "name":"歌手簡介", "key":"V1001_TODAY_SINGER" }, { "name":"菜單", "sub_button":[ { "type":"click", "name":"hello word", "key":"V1001_HELLO_WORLD" }, { "type":"click", "name":"贊一下我們", "key":"V1001_GOOD" }] }] }
首先是菜單項的基類,所有一級菜單、二級菜單都共有一個相同的屬性,那就是name。菜單項基類的封裝代碼如下:
package org.liufeng.weixin.pojo; /** * 按鈕的基類 * * @author liufeng * @date 2013-08-08 */ public class Button { private String name; public String getName() { return name; } public void setName(String name) { this.name = name; } }
接著是子菜單項的封裝。這裡對子菜單是這樣定義的:沒有子菜單的菜單項,有可能是二級菜單項,也有可能是不含二級菜單的一級菜單。這類子菜單項一定會包含三個屬性:type、name和key,封裝的代碼如下:
package org.liufeng.weixin.pojo; /** * 普通按鈕(子按鈕) * * @author liufeng * @date 2013-08-08 */ public class CommonButton extends Button { private String type; private String key; public String getType() { return type; } public void setType(String type) { this.type = type; } public String getKey() { return key; } public void setKey(String key) { this.key = key; } }
再往下是父菜單項的封裝。對父菜單項的定義:包含有二級菜單項的一級菜單。這類菜單項包含有二個屬性:name和sub_button,而sub_button以是一個子菜單項數組。父菜單項的封裝代碼如下:
package org.liufeng.weixin.pojo; /** * 復雜按鈕(父按鈕) * * @author liufeng * @date 2013-08-08 */ public class ComplexButton extends Button { private Button[] sub_button; public Button[] getSub_button() { return sub_button; } public void setSub_button(Button[] sub_button) { this.sub_button = sub_button; } }
最後是整個菜單對象的封裝,菜單對象包含多個菜單項(最多只能有3個),這些菜單項即可以是子菜單項(不含二級菜單的一級菜單),也可以是父菜單項(包含二級菜單的菜單項),如果能明白上面所講的,再來看封裝後的代碼就很容易理解了:
package org.liufeng.weixin.pojo; /** * 菜單 * * @author liufeng * @date 2013-08-08 */ public class Menu { private Button[] button; public Button[] getButton() { return button; } public void setButton(Button[] button) { this.button = button; } }
關於POJO類的封裝就介紹完了。
憑證access_token的獲取方法
繼續在先前通用請求方法的類WeixinUtil.java中加入以下代碼,用於獲取接口訪問憑證:
// 獲取access_token的接口地址(GET) 限200(次/天) public final static String access_token_url = "https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET"; /** * 獲取access_token * * @param appid 憑證 * @param appsecret 密鑰 * @return */ public static AccessToken getAccessToken(String appid, String appsecret) { AccessToken accessToken = null; String requestUrl = access_token_url.replace("APPID", appid).replace("APPSECRET", appsecret); JSONObject jsonObject = httpRequest(requestUrl, "GET", null); // 如果請求成功 if (null != jsonObject) { try { accessToken = new AccessToken(); accessToken.setToken(jsonObject.getString("access_token")); accessToken.setExpiresIn(jsonObject.getInt("expires_in")); } catch (JSONException e) { accessToken = null; // 獲取token失敗 log.error("獲取token失敗 errcode:{} errmsg:{}", jsonObject.getInt("errcode"), jsonObject.getString("errmsg")); } } return accessToken; }
調用封裝的方法創建自定義菜單
// 菜單創建(POST) 限100(次/天) public static String menu_create_url = "https://api.weixin.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN"; /** * 創建菜單 * * @param menu 菜單實例 * @param accessToken 有效的access_token * @return 0表示成功,其他值表示失敗 */ public static int createMenu(Menu menu, String accessToken) { int result = 0; // 拼裝創建菜單的url String url = menu_create_url.replace("ACCESS_TOKEN", accessToken); // 將菜單對象轉換成json字符串 String jsonMenu = JSONObject.fromObject(menu).toString(); // 調用接口創建菜單 JSONObject jsonObject = httpRequest(url, "POST", jsonMenu); if (null != jsonObject) { if (0 != jsonObject.getInt("errcode")) { result = jsonObject.getInt("errcode"); log.error("創建菜單失敗 errcode:{} errmsg:{}", jsonObject.getInt("errcode"), jsonObject.getString("errmsg")); } } return result; }
注意:在運行以上代碼時,需要將appId和appSecret換成你自己公眾號的。
整個工程的結構
為了保證文章的完整獨立性和可讀性,我是新建了一個Java Project(Java web工程也可以,沒有太大關系),沒有在前幾篇文章所講到的weixinCourse工程中添加代碼。如果需要,讀者可以自己實現將菜單創建的代碼移到自己已有的工程中去。
圖中所有Java文件的源代碼都在文章中貼出並進行了說明,圖中使用到的jar也是Java開發中通用的jar包,很容易在網上下載到。
工程中引入的jar包主要分為兩類:
1)第一類是json開發工具包,用於Java對象和Json字符串之間的轉換;json開發工具包一共有3個jar:ezmorph-1.0.6.jar,json-lib-2.2.3-jdk13.jar和morph-1.1.1.jar。
2)第二類是slf4j日志工具包,用於記錄系統運行所產生的日志,日志可以輸出到控制台或文件中。
整個工程中,唯一沒有講到的是src下的log4j.properties的配置,也把它貼出來,方便大家參考,這樣才是一個完整的工程源碼。log4j.properties文件的內容如下:
log4j.rootLogger=info,console,file log4j.appender.console=org.apache.log4j.ConsoleAppender log4j.appender.console.layout=org.apache.log4j.PatternLayout log4j.appender.console.layout.ConversionPattern=[%-5p] %m%n log4j.appender.file=org.apache.log4j.DailyRollingFileAppender log4j.appender.file.DatePattern='-'yyyy-MM-dd log4j.appender.file.File=./logs/weixinmpmenu.log log4j.appender.file.Append=true log4j.appender.file.layout=org.apache.log4j.PatternLayout log4j.appender.file.layout.ConversionPattern=[%-5p] %d %37c %3x - %m%n
如何響應菜單點擊事件
自定義菜單的創建工作已經完成,那麼該如何接收和響應菜單的點擊事件呢,也就是說在公眾帳號後台處理程序中,如何識別用戶點擊的是哪個菜單,以及做出響應。這部分內容其實在教程的第5篇各種消息的接收與響應中已經講解清楚了。
來看一下第一篇教程weixinCourse項目中的CoreService類要怎麼改寫,才能接收響應菜單點擊事件,該類修改後的完整代碼如下:
package org.liufeng.course.service; import java.util.Date; import java.util.Map; import javax.servlet.http.HttpServletRequest; import org.liufeng.course.message.resp.TextMessage; import org.liufeng.course.util.MessageUtil; /** * 核心服務類 * * @author liufeng * @date 2013-05-20 */ public class CoreService { /** * 處理微信發來的請求 * * @param request * @return */ public static String processRequest(HttpServletRequest request) { String respMessage = null; try { // 默認返回的文本消息內容 String respContent = "請求處理異常,請稍候嘗試!"; // xml請求解析 Map<String, String> requestMap = MessageUtil.parseXml(request); // 發送方帳號(open_id) String fromUserName = requestMap.get("FromUserName"); // 公眾帳號 String toUserName = requestMap.get("ToUserName"); // 消息類型 String msgType = requestMap.get("MsgType"); // 回復文本消息 TextMessage textMessage = new TextMessage(); textMessage.setToUserName(fromUserName); textMessage.setFromUserName(toUserName); textMessage.setCreateTime(new Date().getTime()); textMessage.setMsgType(MessageUtil.RESP_MESSAGE_TYPE_TEXT); textMessage.setFuncFlag(0); // 文本消息 if (msgType.equals(MessageUtil.REQ_MESSAGE_TYPE_TEXT)) { respContent = "您發送的是文本消息!"; } // 圖片消息 else if (msgType.equals(MessageUtil.REQ_MESSAGE_TYPE_IMAGE)) { respContent = "您發送的是圖片消息!"; } // 地理位置消息 else if (msgType.equals(MessageUtil.REQ_MESSAGE_TYPE_LOCATION)) { respContent = "您發送的是地理位置消息!"; } // 鏈接消息 else if (msgType.equals(MessageUtil.REQ_MESSAGE_TYPE_LINK)) { respContent = "您發送的是鏈接消息!"; } // 音頻消息 else if (msgType.equals(MessageUtil.REQ_MESSAGE_TYPE_VOICE)) { respContent = "您發送的是音頻消息!"; } // 事件推送 else if (msgType.equals(MessageUtil.REQ_MESSAGE_TYPE_EVENT)) { // 事件類型 String eventType = requestMap.get("Event"); // 訂閱 if (eventType.equals(MessageUtil.EVENT_TYPE_SUBSCRIBE)) { respContent = "謝謝您的關注!"; } // 取消訂閱 else if (eventType.equals(MessageUtil.EVENT_TYPE_UNSUBSCRIBE)) { // TODO 取消訂閱後用戶再收不到公眾號發送的消息,因此不需要回復消息 } // 自定義菜單點擊事件 else if (eventType.equals(MessageUtil.EVENT_TYPE_CLICK)) { // 事件KEY值,與創建自定義菜單時指定的KEY值對應 String eventKey = requestMap.get("EventKey"); if (eventKey.equals("11")) { respContent = "天氣預報菜單項被點擊!"; } else if (eventKey.equals("12")) { respContent = "公交查詢菜單項被點擊!"; } else if (eventKey.equals("13")) { respContent = "周邊搜索菜單項被點擊!"; } else if (eventKey.equals("14")) { respContent = "歷史上的今天菜單項被點擊!"; } else if (eventKey.equals("21")) { respContent = "歌曲點播菜單項被點擊!"; } else if (eventKey.equals("22")) { respContent = "經典游戲菜單項被點擊!"; } else if (eventKey.equals("23")) { respContent = "美女電台菜單項被點擊!"; } else if (eventKey.equals("24")) { respContent = "人臉識別菜單項被點擊!"; } else if (eventKey.equals("25")) { respContent = "聊天唠嗑菜單項被點擊!"; } else if (eventKey.equals("31")) { respContent = "Q友圈菜單項被點擊!"; } else if (eventKey.equals("32")) { respContent = "電影排行榜菜單項被點擊!"; } else if (eventKey.equals("33")) { respContent = "幽默笑話菜單項被點擊!"; } } } textMessage.setContent(respContent); respMessage = MessageUtil.textMessageToXml(textMessage); } catch (Exception e) { e.printStackTrace(); } return respMessage; } }
代碼說明:
1)第69行、第81行這兩行代碼說明了如何判斷菜單的點擊事件。當消息類型MsgType=event,並且Event=CLICK時,就表示是自定義菜單點擊事件;
2)第83行是判斷具體點擊的是哪個菜單項,根據菜單的key值來判斷;
3)第85~109行表示當用戶點擊某個菜單項後,具體返回什麼消息,我只是做個簡單示例,統一返回文本消息,讀者可以根據實際需要來靈活處理。
總結
到這裡關於自定義菜單的創建、菜單事件的判斷和處理響應就全部介紹完了。我只希望看過文章的人不要只是拷貝代碼,如果是這樣,我完全不用花這麼多的時間來寫這篇文章,直接把工程放在下載區多簡單。另外,網上是有很多工具,讓你填入appid,appsecret和菜單結構,提交就能創建菜單,請慎用!因為appid和appsecret一旦告訴別人,你的公眾號的菜單控制權就在別人手上了,總會有別有用心的人出來搞點事的。