DIV CSS 佈局教程網

微信公眾平台開發教程(五):自定義菜單完整解析
編輯:關於JavaScript     

一、為什麼要用自定義菜單

只有一個輸入框的對話頁面,操作起來太像命令列。自定義菜單把常用功能搬到畫面下方,點一下就有效果,更貼近一般使用者的習慣。它不只支援事件回應,也能直接跳轉 URL,遇到比較複雜的功能,跳去自家網頁處理即可。

請注意:自定義菜單只有服務號具備。

二、實作步驟

1. 取得 access_token

access_token 是公眾號呼叫各介面時的全域唯一憑證,正常有效期為 7200 秒,重複取得會讓先前那次失效。用 AppID 與 AppSecret 呼叫下列介面即可取得,所有微信介面都必須走 https。

GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

參數:grant_type 固定填 client_credential;appid 為第三方使用者唯一憑證;secret 為對應密鑰。

成功回傳:

{"access_token":"ACCESS_TOKEN","expires_in":7200}

其中 expires_in 是有效秒數。失敗則回傳錯誤碼,例如 AppID 無效:

{"errcode":40013,"errmsg":"invalid appid"}

2. 建立自定義菜單

目前最多 3 個一級菜單,每個一級菜單最多 5 個二級菜單;一級菜單文字上限 4 個漢字,二級菜單 7 個漢字,超出會以「...」顯示。由於微信客戶端有快取,建立後約需 24 小時才會顯示,測試時可以取消關注再重新關注來立即查看。

按鈕有兩種行為類型:

click:使用者點擊後,微信伺服器會推送一個 event 類型的訊息給開發者,並帶上你自訂的 key,之後就能依 key 做互動。

view:點擊後微信直接開啟按鈕上填寫的網址,適合搭配網頁授權取得使用者資料。

POST https://api.weixin.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN

{
  "button": [
    { "type": "click", "name": "今日歌曲", "key": "V1001_TODAY_MUSIC" },
    { "type": "click", "name": "歌手簡介", "key": "V1001_TODAY_SINGER" },
    {
      "name": "菜單",
      "sub_button": [
        { "type": "view", "name": "搜索", "url": "https://www.soso.com/" },
        { "type": "view", "name": "視頻", "url": "https://v.qq.com/" },
        { "type": "click", "name": "贊一下我們", "key": "V1001_GOOD" }
      ]
    }
  ]
}

參數說明:

  • button(必填):一級菜單陣列,1~3 個。
  • sub_button(選填):二級菜單陣列,1~5 個。
  • type(必填):click 或 view。
  • name(必填):菜單標題,一級不超過 4 個漢字、二級不超過 7 個漢字。
  • key(click 必填):事件 KEY,不超過 128 位元組。
  • url(view 必填):網頁連結,不超過 256 位元組。

成功回傳 {"errcode":0,"errmsg":"ok"};菜單名長度不合法則回傳 {"errcode":40018,"errmsg":"invalid button name size"}。

3. 查詢菜單

GET https://api.weixin.qq.com/cgi-bin/menu/get?access_token=ACCESS_TOKEN

回傳的 JSON 結構與建立時一致,每個節點都會帶一個 sub_button 陣列。

4. 刪除菜單

GET https://api.weixin.qq.com/cgi-bin/menu/delete?access_token=ACCESS_TOKEN

5. 事件接收

使用者點擊後,若按鈕是 click 類型,微信會推送事件;view 類型的點擊不會上報。

<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[FromUser]]></FromUserName>
  <CreateTime>123456789</CreateTime>
  <MsgType><![CDATA[event]]></MsgType>
  <Event><![CDATA[CLICK]]></Event>
  <EventKey><![CDATA[EVENTKEY]]></EventKey>
</xml>

EventKey 就是菜單裡設定的 KEY,靠它決定要回覆什麼。

三、實例演練

延續上一篇的機器人專案,這次加上菜單功能。

1. 取得並快取 access_token

在開發者模式中可以看到並重置 AppID 與 AppSecret。由於 token 有期限,實作時必須自行判斷過期:

private static DateTime GetAccessToken_Time;
private static int Expires_Period = 7200;   // 預設 7200 秒
private static string mAccessToken;

public static string AccessToken {
    get {
        if (string.IsNullOrEmpty(mAccessToken) || HasExpired()) {
            mAccessToken = GetAccessToken(AppID, AppSecret);
        }
        return mAccessToken;
    }
}

private static string GetAccessToken(string appId, string appSecret) {
    string url = string.Format(
        "https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid={0}&secret={1}",
        appId, appSecret);
    string result = HttpUtility.GetData(url);
    XDocument doc = XmlUtility.ParseJson(result, "root");
    XElement root = doc.Root;
    if (root != null) {
        XElement token = root.Element("access_token");
        if (token != null) {
            GetAccessToken_Time = DateTime.Now;
            if (root.Element("expires_in") != null) {
                Expires_Period = int.Parse(root.Element("expires_in").Value);
            }
            return token.Value;
        }
        GetAccessToken_Time = DateTime.MinValue;
    }
    return null;
}

private static bool HasExpired() {
    // 預留一分鐘誤差,避免邊緣時間失效
    if (GetAccessToken_Time != DateTime.MinValue) {
        if (DateTime.Now > GetAccessToken_Time.AddSeconds(Expires_Period).AddSeconds(-60)) {
            return true;
        }
    }
    return false;
}

2. 設定菜單內容

把常見城市做成點擊查詢,另外放一組 view 類型的外連做示範:

{
  "button": [
    {
      "name": "鏈接",
      "sub_button": [
        { "type": "view", "name": "搜索", "url": "https://www.baidu.com/" },
        { "type": "view", "name": "視頻", "url": "https://v.qq.com/" },
        { "type": "click", "name": "贊一下我們", "key": "BTN_GOOD" }
      ]
    },
    {
      "name": "查詢天氣",
      "sub_button": [
        { "type": "click", "name": "武漢", "key": "BTN_TQ_WUHAN" },
        { "type": "click", "name": "上海", "key": "BTN_TQ_SHANGHAI" },
        { "type": "click", "name": "北京", "key": "BTN_TQ_BEIJING" }
      ]
    },
    { "type": "click", "name": "幫助", "key": "BTN_HELP" }
  ]
}

3. 菜單管理

菜單變動不頻繁,把 JSON 放在 txt 檔裡,再寫一個管理頁做四件事:從檔案載入、建立(推送並更新到微信伺服器)、查詢、刪除。

public class MenuManager {
    private static readonly string Menu_Data_Path =
        System.AppDomain.CurrentDomain.BaseDirectory + "/Data/menu.txt";

    public static string GetMenu() {
        string url = string.Format(
            "https://api.weixin.qq.com/cgi-bin/menu/get?access_token={0}", Context.AccessToken);
        return HttpUtility.GetData(url);
    }

    public static void CreateMenu(string menu) {
        string url = string.Format(
            "https://api.weixin.qq.com/cgi-bin/menu/create?access_token={0}", Context.AccessToken);
        HttpUtility.SendHttpRequest(url, menu);
    }

    public static void DeleteMenu() {
        string url = string.Format(
            "https://api.weixin.qq.com/cgi-bin/menu/delete?access_token={0}", Context.AccessToken);
        HttpUtility.GetData(url);
    }

    public static string LoadMenu() {
        return FileUtility.Read(Menu_Data_Path);
    }
}

4. 底層請求方法

GET 與 POST 的細節都封裝在 HttpUtility 裡,正式環境建議再補上重試與逾時處理:

class HttpUtility {
    public static string SendHttpRequest(string url, string data) {
        return SendPostHttpRequest(url, "application/x-www-form-urlencoded", data);
    }

    public static string GetData(string url) {
        return SendGetHttpRequest(url, "application/x-www-form-urlencoded");
    }

    public static string SendPostHttpRequest(string url, string contentType, string requestData) {
        WebRequest request = HttpWebRequest.Create(url);
        request.Method = "POST";
        request.ContentType = contentType;
        byte[] postBytes = Encoding.UTF8.GetBytes(requestData);
        request.ContentLength = postBytes.Length;
        using (Stream outstream = request.GetRequestStream()) {
            outstream.Write(postBytes, 0, postBytes.Length);
        }
        string result = string.Empty;
        using (WebResponse response = request.GetResponse()) {
            if (response != null) {
                using (Stream stream = response.GetResponseStream())
                using (StreamReader reader = new StreamReader(stream, Encoding.UTF8)) {
                    result = reader.ReadToEnd();
                }
            }
        }
        return result;
    }

    public static string SendGetHttpRequest(string url, string contentType) {
        WebRequest request = HttpWebRequest.Create(url);
        request.Method = "GET";
        request.ContentType = contentType;
        string result = string.Empty;
        using (WebResponse response = request.GetResponse()) {
            if (response != null) {
                using (Stream stream = response.GetResponseStream())
                using (StreamReader reader = new StreamReader(stream, Encoding.UTF8)) {
                    result = reader.ReadToEnd();
                }
            }
        }
        return result;
    }
}

class XmlUtility {
    // 把 JSON 轉成 XDocument,方便用 XPath 取值
    public static XDocument ParseJson(string json, string rootName) {
        return JsonConvert.DeserializeXNode(json, rootName);
    }
}

5. 事件分派

view 類型會自動跳轉,不需處理;需要處理的是點擊事件:贊一下、查詢三個城市的天氣、幫助。沿用上一章的事件處理器擴充即可:

class EventHandler : IHandler {
    private string RequestXml { get; set; }

    public EventHandler(string requestXml) {
        this.RequestXml = requestXml;
    }

    public string HandleRequest() {
        string response = string.Empty;
        EventMessage em = EventMessage.LoadFromXml(RequestXml);
        if (em != null) {
            switch (em.Event.ToLower()) {
                case "subscribe":
                    response = SubscribeEventHandler(em);
                    break;
                case "click":
                    response = ClickEventHandler(em);
                    break;
            }
        }
        return response;
    }

    private string SubscribeEventHandler(EventMessage em) {
        TextMessage tm = new TextMessage();
        tm.ToUserName = em.FromUserName;
        tm.FromUserName = em.ToUserName;
        tm.CreateTime = Common.GetNowTime();
        tm.Content = "歡迎您關注***,我是大哥大,有事就問我,呵呵!\n\n";
        return tm.GenerateContent();
    }

    private string ClickEventHandler(EventMessage em) {
        string result = string.Empty;
        if (em != null && em.EventKey != null) {
            switch (em.EventKey.ToUpper()) {
                case "BTN_GOOD":
                    result = btnGoodClick(em);
                    break;
                case "BTN_TQ_BEIJING":
                    result = searchWeather("beijing", em);
                    break;
                case "BTN_TQ_SHANGHAI":
                    result = searchWeather("shanghai", em);
                    break;
                case "BTN_TQ_WUHAN":
                    result = searchWeather("wuhan", em);
                    break;
                case "BTN_HELP":
                    result = btnHelpClick(em);
                    break;
            }
        }
        return result;
    }

    private string btnGoodClick(EventMessage em) {
        TextMessage tm = new TextMessage();
        tm.ToUserName = em.FromUserName;
        tm.FromUserName = em.ToUserName;
        tm.CreateTime = Common.GetNowTime();
        tm.Content = @"謝謝您的支持!";
        return tm.GenerateContent();
    }

    private string btnHelpClick(EventMessage em) {
        TextMessage tm = new TextMessage();
        tm.ToUserName = em.FromUserName;
        tm.FromUserName = em.ToUserName;
        tm.CreateTime = Common.GetNowTime();
        tm.Content = @"查詢天氣,輸入 tq 城市名稱\拼音\首字母";
        return tm.GenerateContent();
    }

    private string searchWeather(string cityName, EventMessage em) {
        TextMessage tm = new TextMessage();
        tm.Content = WeatherHelper.GetWeather(cityName);
        tm.ToUserName = em.FromUserName;   // 發送者與接收者對調
        tm.FromUserName = em.ToUserName;
        tm.CreateTime = Common.GetNowTime();
        return tm.GenerateContent();
    }
}

6. 成果

以上即為本篇全部內容,希望對你的開發有所幫助。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved