Home > Article > Backend Development > WeChat Public Account Development Tutorial Part 14 - Custom Menu Creation and Menu Event Response_PHP Tutorial
WeChat 5.0 released
On August 5, 2013, with the release of WeChat 5.0 iPhone version, the public platform also underwent important updates, including:
1) The operating entity is an organization, and you can choose to become a service account or subscription account;
2) Service accounts can apply for customized menus;
3) Official accounts that use QQ to log in can be upgraded to email login;
4) For public accounts that use email to log in, you can modify the login email;
5) When editing graphic messages, you can optionally fill in the author;
6) Group messages can be synchronized to Tencent Weibo.
Among them, the first two are the ones that everyone talks about the most, which are about the updates of account types and custom menus. I will make some additional explanations here:
1) There are currently two types of public accounts: service accounts and subscription accounts. After the platform update on August 5, all accounts will default to subscription accounts, and there is an opportunity to convert them into service accounts;
2) Service accounts are mainly for businesses, governments and other organizations, while subscription accounts are mainly for media and individuals;
3) Only service accounts can apply for custom menus, subscription accounts cannot;
4) The service account can only send one message per month, while the subscription account can send one message per day.
After the platform was updated, many people struggled with the incompatibility between customizing the menu and sending a group message every day. I don’t want to comment too much on this.
Introduction and summary
Before WeChat 5.0, custom menus were used as a qualification for internal testing. Only a few public accounts had menus, so many companies spent a lot of money to get menus. Nowadays, a large number of accounts have been converted from subscription accounts to service accounts, and many of them are rushing to customize the menu. Moreover, after testing, it was found that WeChat's recent review has been much relaxed. As long as you apply for a service account and customize the menu, you will basically be successful, regardless of the authenticity of the information filled in. I wonder if WeChat will fall out in the future and ask for company information to be completed. It would be like giving a child a piece of candy and then beating him to tears. . .
The custom menu has been applied for. How to create it and how to use it? In recent days, whether in the official WeChat communication group or in the comments on my blog, you can see that many developers are worrying about this. This article will solve this problem for everyone.
Steps to create a custom menu
1. Find the AppId and AppSecret. After the custom menu application is successful, the last two items in "Advanced Functions" - "Development Mode" - "Interface Configuration Information" are;
2. According to the AppId and AppSecret, use the https get method to obtain the access_token, the credential necessary to access the special interface;
3. According to the access_token, submit the menu data in json format through https post.
Analyze the difficulties in creating menus
It turns out that creating a menu is so simple and can be done in three steps? It's almost like putting an elephant in the refrigerator. Haha, of course it's not that simple. Let's look at it step by step. What's the difficulty?
First of all, there is definitely no problem with step 1. As long as you successfully apply for a custom menu, you will definitely get the AppId and AppSecret values.
Let’s look at step 2 again. Since the access_token is obtained through the get method, many people directly put the assembled URL in the browser and execute it, and the access_token is obtained. Regardless of whether it is implemented programmatically, this is a really good idea, and obviously everyone has no problem with the second step.
Finally, let’s look at step 3, assembling the menu data in json format. Although it is a bit complicated, there is basically no problem, because the official gave an example, just copy the cat and the tiger. The problem must occur in https post submission.
Conclusion: Friends who don’t know how to create custom menus can mostly fall into the following three situations:
1) Didn’t read or didn’t understand the description of “General Interface”, “Custom Menu Interface” and “Usage Restrictions” in the public platform API document;
2) Don’t know how to initiate an HTTPS request (usual http requests can be easily handled directly using HttpUrlConnection, but https requests are a bit more complicated);
3) I don’t know how to submit menu data in json format through POST.
If you are reading the article and don’t know which one it belongs to, or if there are several cases, you may wish to leave a message or do a survey. No matter which situation it is, now that you have read this article, I believe it will help you figure it out.
Interpretation of common interface documents---obtaining credentials
Let’s first look at the introduction part of the general interface document, as shown in the figure below.
To put it simply, this introduction can be understood as follows: the public platform also has many special interfaces, such as the creation of custom menus, acquisition of voice files, proactive sending of messages, etc. If developers want to access these special interfaces through HTTP requests, interface, you must have access credentials, that is, access_token.
So, how to obtain the interface access credential access_token? Let's move on.
The picture has made it very clear. To obtain the access_token, you need to access the following link through GET:
https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET
There are three parameters in the link, namely grant_type, appid and secret. According to the parameter description in the figure, grant_type passes the fixed value client_credential, and appid and secret are assigned to us by WeChat after applying for a custom menu.
After the request is sent successfully, the WeChat server will return a json string containing two elements: access_token and expires_in. Among them, access_token is the certificate we ultimately need, and expires_in is the validity period of the certificate, in seconds, 7200 seconds is 2 hours. This means that you do not need to obtain the access_token again every time you access a special interface. As long as the access_token is still valid, it can always be used.
Interpretation of custom menu interface documentation
Still the same, let’s take a look at the introduction of the custom menu interface, as shown in the figure below.
We can get the following information from the picture:
1) After getting the access_token, we can perform three operations on the menu: create, query and delete;
2) The custom menu currently only supports click events, that is, the user replies to a certain type of message after clicking; it is not possible to directly open the page by clicking on the menu item (type=view is not open, and is currently only available in micro-life);
3) Due to WeChat client caching, the menu will not be displayed on WeChat immediately after it is created, and it will take 24 hours. When creating a test menu, you can view the menu immediately by unfollowing and then following again.
Continue reading below for an introduction to how to create a menu, as shown in the picture below.
In fact, it is to submit a menu string in JSON format to the address https://api.weixin.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN in POST mode.
Later, I won’t explain the parameter descriptions one by one with pictures. I’ll just talk about the key points:
1) The custom menu has a 3x5 structure, that is, the menu can only have a maximum of two levels, a maximum of 3 first-level menus, and a maximum of 5 second-level menu items under each first-level menu;
2) Menu items have a key value. When the user clicks on a menu item, WeChat will send the key value of the menu item to our background handler in the form of event push.
I won’t mention the query and creation of menus. The frequency of use of these two interfaces is very small and generally not used. If necessary, it is not difficult to understand according to the ideas I provided above.
Interpret the usage restrictions of API documentation
Many friends started to wonder when they saw this picture: Why is there a limit on the number of times the menu can be used? When the number of users is increasing, it is simply not enough. Please see clearly that this limit is for interface calls, that is, for developers, and has nothing to do with the number of users or the number of uses.
Let’s take the certificate acquisition interface as an example. It is limited to 200 calls per day. Remember that we mentioned earlier that access_token has a validity period, and the validity period is two hours, that is, you can continue to use it within two hours after obtaining an access_token. So ideally, within 24 hours a day, do you only need to obtain it 12 times? Enough? Isn't 200 times enough?
Let’s look at the menu creation interface limit which can only be called 100 times a day. Let me explain it this way. After the menu is created once, as long as you do not switch modes (referring to switching between editing mode and development mode) or call the delete interface, this menu will exist forever. Who has nothing to do and has to create a menu 100 times a day? Even if it is a test, testing 10 times and 8 times is enough, right?
I won’t explain the limitations of the menu query and delete interfaces. I have never used these two interfaces so far. Even if there is such a demand, calling it so many times a day is completely enough.
Encapsulates common request methods
After reading this, it is assumed that everyone has mastered all the theoretical knowledge about custom menus mentioned above, and now we will enter the practical explanation of the code.
We learned earlier that creating a menu requires calling two interfaces, and both are https requests, not http. If you want to encapsulate a general request method, the method needs to have at least the following capabilities:
1) Support HTTPS requests;
2) Supports GET and POST methods;
3) Supports parameter submission and no parameters;
对于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一旦告诉别人,你的公众号的菜单控制权就在别人手上了,总会有别有用心的人出来搞点事的。