微信公眾號開發C#系列-11、生成帶參數二維碼應用場景

我們在[微信公眾號開發C#系列-7、消息管理-接收事件推送](http://blog.rdiframework.net/article/211)章節有對掃描帶參數二維碼事件的處理做了講解。本篇主要講解通過微信公眾號開發平臺提供的接口生成帶參數的二維碼及應用場景。微信公眾號平臺提供了生成帶參數二維碼的接口，使用該接口可以獲得多個帶不同場景值的二維碼，用戶掃描后，公眾號可以接收到事件推送。目前有2種類型的二維碼，分別是臨時二維碼和永久二維碼，前者有過期時間，最大為1800秒，但能夠生成較多數量，后者無過期時間，數量較少（目前參數只支持1--100000）。兩種二維碼分別適用于帳號綁定、用戶來源統計等場景。

1、概述

我們在微信公眾號開發C#系列-7、消息管理-接收事件推送章節有對掃描帶參數二維碼事件的處理做了講解。本篇主要講解通過微信公眾號開發平臺提供的接口生成帶參數的二維碼及應用場景。

微信公眾號平臺提供了生成帶參數二維碼的接口，使用該接口可以獲得多個帶不同場景值的二維碼，用戶掃描后，公眾號可以接收到事件推送。
目前有2種類型的二維碼，分別是臨時二維碼和永久二維碼，前者有過期時間，最大為1800秒，但能夠生成較多數量，后者無過期時間，數量較少（目前參數只支持1--100000）。兩種二維碼分別適用于帳號綁定、用戶來源統計等場景。

用戶掃描帶場景值二維碼時，可能推送以下兩種事件：

如果用戶還未關注公眾號，則用戶可以關注公眾號，關注后微信會將帶場景值關注事件推送給開發者。
如果用戶已經關注公眾號，在用戶掃描后會自動進入會話，微信也會將帶場景值掃描事件推送給開發者。

獲取帶參數的二維碼的過程包括兩步，首先創建二維碼ticket，然后憑借ticket到指定URL換取二維碼。

2、創建二維碼ticket

每次創建二維碼ticket需要提供一個開發者自行設定的參數（scene_id），分別介紹臨時二維碼和永久二維碼的創建二維碼ticket過程。

2.1、創建臨時二維碼接口說明

http請求方式: POST

URL: https://api.weixin.qq.com/cgi-bin/qrcode/create?access_token=TOKEN
POST數據格式：json
POST數據例子：
{"expire_seconds": 604800, "action_name": "QR_SCENE", "action_info": {"scene": {"scene_id": 123}}}

或者也可以使用以下POST數據創建字符串形式的二維碼參數：

{"expire_seconds": 604800, "action_name": "QR_STR_SCENE", "action_info": {"scene": {"scene_str": "test"}}}

2.2、創建永久二維碼接口說明

http請求方式: POST
URL: https://api.weixin.qq.com/cgi-bin/qrcode/create?access_token=TOKEN
POST數據格式：json
POST數據例子：{"action_name": "QR_LIMIT_SCENE", "action_info": {"scene": {"scene_id": 123}}}

或者也可以使用以下POST數據創建字符串形式的二維碼參數：
{"action_name": "QR_LIMIT_STR_SCENE", "action_info": {"scene": {"scene_str": "test"}}}

2.3、參數說明

參數說明

參數	說明
expire_seconds	該二維碼有效時間，以秒為單位。最大不超過2592000（即30天），此字段如果不填，則默認有效期為30秒。
action_name	二維碼類型，QR_SCENE為臨時的整型參數值，QR_STR_SCENE為臨時的字符串參數值，QR_LIMIT_SCENE為永久的整型參數值，QR_LIMIT_STR_SCENE為永久的字符串參數值
action_info 二維碼詳細信息
scene_id	場景值ID，臨時二維碼時為32位非0整型，永久二維碼時最大值為100000（目前參數只支持1--100000）
scene_str	場景值ID（字符串形式的ID），字符串類型，長度限制為1到64

返回說明

正確的Json返回結果:

{"ticket":"gQH47joAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL2taZ2Z3TVRtNzJXV1Brb3ZhYmJJAAIEZ23sUwMEmm3sUw==","expire_seconds":60,"url":"http://weixin.qq.com/q/kZgfwMTm72WWPkovabbI"}

參數	說明
ticket	獲取的二維碼ticket，憑借此ticket可以在有效時間內換取二維碼。
expire_seconds	該二維碼有效時間，以秒為單位。最大不超過2592000（即30天）。
url	二維碼圖片解析后的地址，開發者可根據該地址自行生成需要的二維碼圖片

2.4、通過ticket換取二維碼

獲取二維碼ticket后，開發者可用ticket換取二維碼圖片。請注意，本接口無須登錄態即可調用。
請求說明

HTTP GET請求（請使用https協議）https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=TICKET

提醒：TICKET記得進行UrlEncode

返回說明

ticket正確情況下，http 返回碼是200，是一張圖片，可以直接展示或者下載。

HTTP頭（示例）如下：
Accept-Ranges:bytes
Cache-control:max-age=604800
Connection:keep-alive
Content-Length:28026
Content-Type:image/jpg
Date:Wed, 16 Oct 2013 06:37:10 GMT
Expires:Wed, 23 Oct 2013 14:37:10 +0800
Server:nginx/1.4.1
錯誤情況下（如ticket非法）返回HTTP錯誤碼404。

3、創建與獲取臨時或永久二維碼代碼參考

我們可以直接使用Senparc.Weixin SDK提供的接口Senparc.Weixin.MP.AdvancedAPIs.QrCodeApi.Create來創建臨時或永久二維碼。

利用Senparc.Weixin.MP.AdvancedAPIs.QrCodeApi.GetShowQrCodeUrl來獲取臨時或永久二維碼。

Senparc.Weixin.MP.AdvancedAPIs.QrCodeApi代碼參考：

//API：http://mp.weixin.qq.com/wiki/index.php?title=%E7%94%9F%E6%88%90%E5%B8%A6%E5%8F%82%E6%95%B0%E7%9A%84%E4%BA%8C%E7%BB%B4%E7%A0%81

/// <summary>
/// 二維碼接口
/// </summary>
public static class QrCode
{
    /// <summary>
    /// 創建二維碼
    /// </summary>
    /// <param name="expireSeconds">該二維碼有效時間，以秒為單位。 最大不超過1800。0時為永久二維碼</param>
    /// <param name="sceneId">場景值ID，臨時二維碼時為32位整型，永久二維碼時最大值為1000</param>
    /// <returns></returns>
    public static CreateQrCodeResult Create(string accessToken, int expireSeconds, int sceneId)
    {
        var urlFormat = "https://api.weixin.qq.com/cgi-bin/qrcode/create?access_token={0}";
        object data = null;
        if (expireSeconds > 0)
        {
            data = new
            {
                expire_seconds = expireSeconds,
                action_name = "QR_SCENE",
                action_info = new
                {
                    scene = new
                    {
                        scene_id = sceneId
                    }
                }
            };
        }
        else
        {
            data = new
            {
                action_name = "QR_LIMIT_SCENE",
                action_info = new
                {
                    scene = new
                    {
                        scene_id = sceneId
                    }
                }
            };
        }
        return CommonJsonSend.Send<CreateQrCodeResult>(accessToken, urlFormat, data);
    }

    /// <summary>
    /// 獲取二維碼（不需要AccessToken）
    /// 錯誤情況下（如ticket非法）返回HTTP錯誤碼404。
    /// </summary>
    /// <param name="ticket"></param>
    /// <param name="stream"></param>
    public static void ShowQrCode(string ticket, Stream stream)
    {
        var urlFormat = "https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket={0}";
        HttpUtility.Get.Download(string.Format(urlFormat, ticket), stream);
    }
}

4、二維碼創建實現

要使用微信提供的永久或臨時二維碼的功能，我們需要界面來生成或獲取二維碼，如下圖所示。

創建二維碼

控制器代碼參考：

[HttpPost]
[ValidateInput(false)]
[LoginAuthorize]
public ActionResult GenerateQrCode()
{
    string ticket = CacheFactory.Cache().GetCache<string>("Weixin-Qr-Ticket");
    if (string.IsNullOrEmpty(ticket))
    {
        WeixinOfficialAccountEntity currentWeixinOfficialAccountEntity = RDIFrameworkService.Instance.WeixinBasicService.GetCurrentOfficialAccountEntity(ManageProvider.Provider.Current());
        string token = currentWeixinOfficialAccountEntity.AccessToken;
        var result = Senparc.Weixin.MP.AdvancedAPIs.QrCodeApi.Create(token, 600, 10, Senparc.Weixin.MP.QrCode_ActionName.QR_SCENE);
        if (result.errcode == Senparc.Weixin.ReturnCode.請求成功)
        {
            ticket = result.ticket;
            CacheFactory.Cache().WriteCache<string>(result.ticket, "Weixin-Qr-Ticket", DateTime.Now.AddSeconds(600));
        }
    }

    string qrUrl = Senparc.Weixin.MP.AdvancedAPIs.QrCodeApi.GetShowQrCodeUrl(ticket);
    return Content(new JsonMessage { Success = true, Data = qrUrl, Type = ResultType.Success, Message = RDIFrameworkMessage.MSG3010 }.ToString());
}

上面的代碼我們創建了一個場景值為10的臨時二維碼。用戶通過掃描這個二維碼，我們就可以在服務器端做處理，掃描帶參數二維碼事件只需要重寫OnEvent_ScanRequest事件代碼即可，如下我們返回了一個文本消息，實現代碼參考：

public override IResponseMessageBase OnEvent_ScanRequest(RequestMessageEvent_Scan requestMessage)
{
    //通過掃描關注
    var responseMessage = CreateResponseMessage<ResponseMessageText>();

    responseMessage.Content = responseMessage.Content ?? string.Format("歡迎關注國思軟件，通過掃描二維碼進入，場景值：{0}", requestMessage.EventKey);

    return responseMessage;
}

在上面的代碼中用戶掃描了帶場景值的二維碼進入公眾號后我們返回了一個提示的文本消息。這是非常有用的功能，常用途推廣，可以根據不同的二維碼場景值分別做不同的業務處理，如可以統計關注的每一個粉絲從哪里來的，做到渠道推廣分析，但是關注的都是同一個公眾號。

通過掃描帶場景值的二維碼進入

5、生成帶參數的二維碼用途

微信公眾號生成帶參數的二維碼有何用途？

可以區分粉絲來源，只需要生成不同的帶參數的二維碼，把這些二維碼分別投放到各個渠道，粉絲通過這些渠道二維碼進來就可以區分粉絲來源，微號幫后臺渠道粉絲列表中有粉絲數及明細；
粉絲通過掃描渠道二維碼關注公眾號，會打標簽分組，比如粉絲掃商店A、B的二維碼進來的，在微信公眾號后來的用戶管理中可查看到商店A/B二維碼名下的粉絲明細及分組情況；
可以生成多個不同的渠道二維碼配置不同的營銷活動，設置不同的關注回復信息，讓粉絲第一時間了解活動動機，是否有興趣參與等等；
可以利用渠道二維碼生成功能，可以實現微信收款前關注公眾號，間接分析粉絲后續消費情況；
考核推廣員完成任務的進度，如以推廣名字生成多不個同的二維碼，分配給不同的推廣員，每個推廣員吸引了多少粉絲關注公眾號，微號幫后臺都可以一一明細；
帶參數的二維碼也叫渠道二維碼或者場景二維碼，生存的數量有限，且是永久二維碼。當數量用完后可以刪除一些不用的二維碼釋放出來，二次利用。
其他用途。