避坑指南)
微信小程序做消息推送前前后后折騰了大半年從最開始的模板消息一路踩到訂閱消息中間被各種文檔坑得夠嗆。今天把這段經(jīng)驗完整整理出來標(biāo)題就叫從模板消息到訂閱消息的實戰(zhàn)避坑指南——這不僅僅是接口替換的問題整個推送體系的思路都變了。如果你正準(zhǔn)備給自己的小程序接入推送或者正在被用戶授權(quán)了為什么還是發(fā)不出去折磨這篇文章應(yīng)該能幫你少走不少彎路。先說結(jié)論消息推送這事方案選型比代碼實現(xiàn)重要得多。微信把模板消息砍掉、全面轉(zhuǎn)向訂閱消息本質(zhì)上是把推送主動權(quán)從開發(fā)者手里拿回來一部分交給用戶。你可以在用戶每次操作后請求一次訂閱授權(quán)攢夠了授權(quán)額度再定向推送。這套機(jī)制看起來簡單但實際跑起來會發(fā)現(xiàn)授權(quán)時機(jī)、額度消耗、模板字段、調(diào)試環(huán)境這些環(huán)節(jié)處處是坑。1. 先把規(guī)則吃透模板消息為什么退場訂閱消息到底怎么運(yùn)作1.1 模板消息退場的真實原因不是技術(shù)不行是容易騷擾用戶老開發(fā)者應(yīng)該都記得模板消息的流程用戶在小程序里完成一次操作后彈窗征求用戶同意同意后開發(fā)者就能在后續(xù)任意時間點給用戶推送模板消息而且推送次數(shù)不受嚴(yán)格限制。我早期的項目就是靠這個做訂單狀態(tài)通知的體驗確實方便用戶只要授權(quán)一次后面發(fā)貨、簽收、售后每個節(jié)點都能推。但問題恰恰出在授權(quán)一次永久使用上。很多小程序把模板消息當(dāng)免費(fèi)短信用用戶稍微有點互動就狂推營銷內(nèi)容最終結(jié)果就是用戶被騷擾到直接把小程序的通知權(quán)限關(guān)了。微信官方后來把模板消息逐步下線新注冊的小程序后臺已經(jīng)看不到模板消息入口老接口也在 2020 年初徹底停用。本質(zhì)原因就一句話這種授權(quán)模式?jīng)]法約束開發(fā)者必須改成一次授權(quán)、一次推送的單次消耗模型這就是訂閱消息的雛形。1.2 訂閱消息的規(guī)則核心授權(quán)一次只能推一條訂閱消息最核心的規(guī)則就一句用戶的每次允許授權(quán)只對應(yīng)一次消息推送的額度。用戶點了允許你拿到一條推送額度用掉之后想再推必須讓用戶再次授權(quán)。這個設(shè)計意味著你不能像以前那樣先囤授權(quán)再慢慢推而要把推送動作和用戶的具體操作強(qiáng)綁定。比如用戶下單成功后你彈訂閱框拿到額度后立刻發(fā)送下單成功通知這就是最標(biāo)準(zhǔn)的一次消耗閉環(huán)。如果你想在發(fā)貨時再推一條就要在用戶下單時多次彈窗請求授權(quán)或者等到發(fā)貨前再找機(jī)會觸發(fā)授權(quán)彈窗。很多第一次做訂閱消息的開發(fā)者會習(xí)慣性地問用戶每點一次允許我只能推一條那我的業(yè)務(wù)有五個節(jié)點需要通知怎么辦答案只有一個你的業(yè)務(wù)需要在不同的用戶動作節(jié)點上分別去拿對應(yīng)的授權(quán)。比如下單節(jié)點拿下單成功通知的授權(quán)發(fā)貨節(jié)點拿發(fā)貨提醒的授權(quán)每一個節(jié)點獨立授權(quán)、獨立消耗。1.3 一次性訂閱和長期訂閱別再混為一談了訂閱消息分為兩種一次性訂閱消息和長期訂閱消息。一次性訂閱消息是目前絕大多數(shù)小程序都在用的類型任何主體都能申請用戶每次授權(quán)對應(yīng)一條推送額度。長期訂閱消息則完全不同。它允許開發(fā)者一次授權(quán)后在用戶沒有再次操作的情況下多次推送但它對行業(yè)類目有嚴(yán)格限制僅限醫(yī)療、政務(wù)、金融、教育等民生服務(wù)領(lǐng)域個人主體和絕大多數(shù)普通企業(yè)主體根本沒資格申請。我在后臺翻過類目列表普通電商、工具類目基本找不到長期訂閱的入口。所以對大部分開發(fā)者來說只需要無腦關(guān)注一次性訂閱消息就行。如果有人在技術(shù)社區(qū)跟你說我這里可以開通長期訂閱基本可以斷定是違規(guī)代開通或者營銷騙局微信對這種灰色操作的打擊力度很大不要碰。2. 前端實戰(zhàn)授權(quán)鏈路從 openid 開始2.1 openid 從哪來code 換 openid 的基礎(chǔ)流程不能錯訂閱消息推送時后端必須知道接收者的 openid這個 openid 是每個用戶在每個小程序下的唯一標(biāo)識。獲取 openid 的標(biāo)準(zhǔn)姿勢就是 wx.login 拿 code然后后端拿著 code 換 openid 和 session_key。前端只有一小段代碼// 前端用戶進(jìn)入小程序時執(zhí)行 wx.login({ success(res) { if (res.code) { // 把 code 傳給后端 wx.request({ url: https://your-api.com/api/login, data: { code: res.code }, success(result) { // 后端返回 openid前端可以存起來備用 console.log(result.data.openid) } }) } } })后端拿到 code 后調(diào)微信的 jscode2session 接口GET https://api.weixin.qq.com/sns/jscode2session?appidAPPIDsecretAPPSECRETjs_codeCODEgrant_typeauthorization_code注意兩個坑第一這個接口用的是 appid 加 secret不需要 access_token很多人會下意識以為所有微信接口都要帶 access_token結(jié)果在這里先卡一道第二code 有效期只有 5 分鐘而且只能用一次用完作廢。我之前排過一個線上問題前端并發(fā)請求把同一個 code 用了兩次第二次直接報 invalid code排查了半天才發(fā)現(xiàn)是重復(fù)消費(fèi)了。換回來的結(jié)果是一個 JSON包含 openid 和 session_key。openid 建議在后端直接和用戶體系綁定不要反復(fù)通過前端傳來傳去避免被偽造。2.2 授權(quán)彈窗的正確喚起姿勢別在 onLoad 里瞎彈wx.requestSubscribeMessage 是前端拉起訂閱授權(quán)彈窗的接口但它的調(diào)用時機(jī)非常有講究。最基礎(chǔ)的規(guī)則是必須在用戶點擊行為tap的同步回調(diào)里調(diào)用不能在 onLoad、onShow 這些生命周期里直接彈否則在某些基礎(chǔ)庫版本下會出現(xiàn)接口調(diào)用成功但彈窗死活不出來的情況或者被微信靜默降級處理。更深一層的問題是頻控。如果用戶在一段時間內(nèi)被你反復(fù)彈窗詢問訂閱微信會直接限制你的彈窗喚起權(quán)限。我實測下來的體感是同一用戶同一模板短時間內(nèi)彈兩次以上第二次彈窗出來的概率就明顯下降如果用戶連續(xù)拒絕兩三次后面基本就彈不出來了。所以正確做法是不要在頁面加載時就請求訂閱而要把訂閱動作綁定到真實的業(yè)務(wù)操作節(jié)點上。比如下單成功、支付完成、報名成功這些用戶主動完成動作的按鈕回調(diào)里順勢彈出訂閱框。用戶剛完成一個動作心理預(yù)期里確實需要收到后續(xù)通知這時候彈窗的接受率最高。2.3 前端實操代碼一個干凈的訂閱按鈕示例下面這個示例是支付成功后引導(dǎo)用戶訂閱訂單狀態(tài)通知的標(biāo)準(zhǔn)寫法。// 支付成功回調(diào)里觸發(fā)訂閱 function handlePaySuccess(orderId) { // 先做業(yè)務(wù)請求再拉起訂閱 wx.requestSubscribeMessage({ tmplIds: [TEMPLATE_ID_HERE], // 在 mp 后臺申請到的模板 ID success(res) { // 返回結(jié)果是一個對象key 是模板 ID if (res[TEMPLATE_ID_HERE] accept) { // 用戶點了允許拿到一條推送額度 // 把授權(quán)結(jié)果上報后端由后端記錄授權(quán)庫存 reportSubscribeAuth(orderId, TEMPLATE_ID_HERE) } else if (res[TEMPLATE_ID_HERE] reject) { // 用戶拒絕不要反復(fù)彈 console.log(用戶拒絕了訂閱) } else if (res[TEMPLATE_ID_HERE] ban) { // 被微信限制彈窗需要引導(dǎo)用戶去設(shè)置頁手動開啟 console.log(訂閱被限制) } }, fail(err) { // 彈窗喚起失敗常見原因是調(diào)用時機(jī)不對或頻控 console.error(訂閱調(diào)用失敗, err) } }) }重點說一下返回值的判斷。wx.requestSubscribeMessage 的 success 回調(diào)里返回值是一個以模板 ID 為 key 的對象value 有三種情況accept 表示允許、reject 表示拒絕、ban 表示被限制。很多人只判斷了 success 就默認(rèn)用戶一定允許了這是不嚴(yán)謹(jǐn)?shù)?。必須根?jù)模板 ID 逐個取 value再看是不是 accept。另外 tmplIds 參數(shù)一次最多傳 3 個模板 ID這是官方限制。但我實際測試下來一次彈 3 個模板的轉(zhuǎn)化率會明顯下降用戶看到三連彈窗往往直接全拒。我的建議是一個業(yè)務(wù)節(jié)點只彈一個最相關(guān)的模板寧可多設(shè)計幾個觸發(fā)節(jié)點也別在一個彈窗里塞多個模板。3. 后端發(fā)送access_token、模板字段與接口調(diào)試3.1 access_token 的緩存策略別每次都去換會被限流后端發(fā)送訂閱消息前必須拿到 access_token這是調(diào)用所有微信 cgi-bin 接口的通行證。access_token 的有效期是 7200 秒兩小時每次獲取都有頻率限制每日獲取上限是 2000 次。如果用戶量稍微上來一點每次發(fā)送都現(xiàn)取 token很容易把 2000 次配額打爆接著就會報 45009接口調(diào)用超過限額。我比較推薦的做法是內(nèi)存緩存加過期時間JVM 或 Node 進(jìn)程里掛一個定時刷新任務(wù)提前 5 分鐘把 token 續(xù)上。偽代碼如下let cachedToken null let tokenExpireTime 0 async function getAccessToken() { // 提前 5 分鐘刷新避免邊緣過期 if (cachedToken tokenExpireTime - 300 Date.now()) { return cachedToken } const url https://api.weixin.qq.com/cgi-bin/token?grant_typeclient_credentialappid${APPID}secret${APPSECRET} const res await axios.get(url) cachedToken res.data.access_token tokenExpireTime Date.now() res.data.expires_in * 1000 return cachedToken }如果是多實例部署建議把 token 放到 Redis 里加鎖更新避免多個實例同時去刷新導(dǎo)致 token 互相覆蓋。這一點在線上環(huán)境很重要我見過測試環(huán)境單機(jī)跑著沒事一上生產(chǎn)多實例部署立刻出現(xiàn) 40001 的案例原因就是各實例各自緩存了不同的 token后一個獲取的把前一個頂?shù)袅恕?.2 訂閱消息發(fā)送接口Node.js 完整示例發(fā)送訂閱消息的接口是POST https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_tokenACCESS_TOKEN請求體是一個 JSON{ touser: OPENID, template_id: TEMPLATE_ID, page: pages/order/detail?id123, miniprogram_state: formal, lang: zh_CN, data: { thing1: { value: 您的訂單已發(fā)貨 }, time2: { value: 2024年6月30日 15:00 }, character_string3: { value: SF1234567890 } } }對應(yīng) Node.js 后端代碼const axios require(axios) async function sendSubscribeMessage(openid, templateId, data, page) { const token await getAccessToken() const url https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_token${token} const body { touser: openid, template_id: templateId, page: page || pages/index/index, miniprogram_state: formal, lang: zh_CN, data } const res await axios.post(url, body) if (res.data.errcode 0) { // 發(fā)送成功同時消耗一條用戶授權(quán)額度 return { success: true } } else { // 發(fā)送失敗根據(jù) errcode 做不同處理 return { success: false, errcode: res.data.errcode, errmsg: res.data.errmsg } } }這里有一個很多新手會卡住的點miniprogram_state 參數(shù)。它有三個可選值developer開發(fā)版、trial體驗版、formal正式版。如果你當(dāng)前測試的小程序是體驗版但 miniprogram_state 傳了 formal接口可能返回成功但用戶手機(jī)上根本收不到這條訂閱消息。反過來也一樣正式版環(huán)境用 developer 也收不到。正確的測試姿勢是開發(fā)調(diào)試時用 developer 或 trial發(fā)布上線后用 formal。我當(dāng)時就是在體驗版環(huán)境測試忘了改這個參數(shù)結(jié)果后端日志顯示發(fā)送成功手機(jī)一直收不到排查了一個下午才發(fā)現(xiàn)是環(huán)境狀態(tài)不匹配。3.3 data 字段匹配模板字段的類型和長度限制訂閱消息的 data 字段是最容易報 47003參數(shù)格式錯誤的地方。你在 mp 后臺申請模板時模板里每個字段都有固定的 key比如 thing1、time2、number3、character_string4 這些。data 里的 key 必須和模板字段完全一致少一個、多一個、key 名寫錯都會直接報錯。每種字段類型對 value 的格式和長度都有硬性限制thing20 個以內(nèi)漢字適合放物品名、訂單備注等文本number數(shù)字類型適合放金額、數(shù)量time時間格式需要按指定格式傳一般是2024年6月30日 15:00這種樣式character_string20 個以內(nèi)字符適合放訂單號、快遞單號phrase5 個以內(nèi)漢字適合放一句話狀態(tài)我踩過最深的坑是 thing 和 phrase 的長度限制。開發(fā)時測試數(shù)據(jù)短沒事一上線用戶輸入長一點就直接報 47003。有個比較穩(wěn)妥的處理后端在組裝 data 之前先對每個字段做長度截斷或校驗超長的給用戶提示別讓臟數(shù)據(jù)打到微信接口。4. 從模板消息遷移到訂閱消息一份改造清單4.1 模板 ID 的變化從老接口到新模板 ID模板消息時代模板 ID 一般是一串很長的數(shù)字加字母混合的值訂閱消息的模板 ID 則是 T 字母開頭的一串字符。你在 mp 后臺的訂閱消息模塊里申請模板審核通過后就能拿到 T 開頭的模板 ID。申請的路徑是登錄微信公眾平臺 → 功能 → 訂閱消息 → 公共模板庫 → 選類目 → 選關(guān)鍵詞 → 組合成自定義模板。關(guān)鍵詞是從該行業(yè)類目下的固定詞庫里選的不能自己隨意造詞。比如電商類目下會有訂單發(fā)貨提醒物流簽收通知這些關(guān)鍵詞可用。申請審核一般比較快快的時候幾小時就過了慢的話一到兩個工作日。我建議提前把業(yè)務(wù)需要的模板一次性申請好別等上線了再補(bǔ)審核期間業(yè)務(wù)會卡住。從模板消息遷移到訂閱消息時你舊的后端邏輯里所有調(diào)用模板消息發(fā)送接口的地方都要換成訂閱消息接口模板 ID 全部替換授權(quán)邏輯也要重寫。相比代碼改動業(yè)務(wù)邏輯的調(diào)整更關(guān)鍵模板消息是一次授權(quán)無限推送訂閱消息是一次授權(quán)一條推送你的推送節(jié)點設(shè)計、授權(quán)觸發(fā)時機(jī)全都要重新規(guī)劃。4.2 授權(quán)庫存管理把每條授權(quán)當(dāng)成一種資產(chǎn)訂閱消息的授權(quán)額度是稀缺資源不能隨用隨丟。我建議后端建一張表專門記錄授權(quán)和消耗情況用戶 openid模板 ID授權(quán)時間是否已消耗消耗時間關(guān)聯(lián)的業(yè)務(wù)單號用戶在哪個業(yè)務(wù)節(jié)點授權(quán)了哪個模板額度是否已經(jīng)用來發(fā)送過消息都要能隨時查出來。后面如果用戶投訴我沒授權(quán)怎么給我推消息你可以直接拉出這張表自證清白。這里涉及一個關(guān)鍵的消費(fèi)邏輯當(dāng)你調(diào)用發(fā)送接口返回 errcode 0 之后微信默認(rèn)消耗了用戶的一次授權(quán)。如果返回的是 43101用戶拒絕說明當(dāng)前沒有可用授權(quán)額度這次發(fā)送不消耗任何額度。但要注意一種特殊情況用戶剛在前端點完允許你立刻在后端發(fā)消息有一定概率仍然返回 43101因為微信服務(wù)端對授權(quán)狀態(tài)的寫入存在輕微延遲。我的解決辦法是授權(quán)后不立即發(fā)送而是把發(fā)送任務(wù)丟進(jìn)延遲隊列等 5 到 10 秒再發(fā)實測能把 43101 的概率降到很低。4.3 提高送達(dá)率的三個手段別只會調(diào)接口訂閱消息能不能真正到達(dá)用戶手機(jī)接口返回成功只是第一步用戶是否愿意點開、是否愿意繼續(xù)授權(quán)才是關(guān)鍵。第一授權(quán)彈窗的時機(jī)要貼近用戶真實需求。下單成功后問要不要接收發(fā)貨提醒通過率很高用戶剛打開首頁就彈允許我們給你推送消息基本是找拒。把訂閱動作嵌到業(yè)務(wù)流程里而不是做成獨立環(huán)節(jié)。第二推送內(nèi)容要一條是一條。訂閱消息的本質(zhì)是服務(wù)通知不是營銷短信。模板里能放的字?jǐn)?shù)有限你更應(yīng)該確保每條消息對用戶有實際價值。我見過一個電商項目用戶一注冊就被彈訂閱彈窗通過率不到 10%后來改成支付完成頁彈發(fā)貨通知通過率直接翻倍。第三要關(guān)注用戶主動關(guān)閉通知的情況。用戶在小程序右上角的...菜單里可以關(guān)閉整個小程序的服務(wù)通知開關(guān)關(guān)閉后你發(fā)訂閱消息接口照樣返回成功但用戶收不到。這不是技術(shù)能解決的只能靠內(nèi)容質(zhì)量把用戶求回來。5. 高頻報錯排查與避坑實錄5.1 高頻報錯速查表這里整理了我實際開發(fā)中遇到的幾個高頻錯誤碼建議大家收藏備查錯誤碼錯誤含義排查思路40001access_token 無效或過期檢查 token 緩存邏輯是否多實例互相覆蓋重新獲取40003openid 不正確確認(rèn) openid 是否來自同一小程序前后端環(huán)境是否一致40037模板 ID 不正確確認(rèn)模板 ID 是否 T 開頭是否在后臺申請通過41030page 路徑不正確page 必須以 pages/ 開頭且在 app.json 中注冊43101用戶拒絕接受消息授權(quán)額度已消耗或用戶拒絕了授權(quán)檢查授權(quán)庫存47003參數(shù)格式錯誤檢查 data 字段 key、value 類型和長度限制45009接口調(diào)用超過限額access_token 是否做了緩存是否觸發(fā)微信頻控43101 是大家遇到最多的錯誤但它的原因其實就那么幾個要么用戶確實拒絕了彈窗要么額度已經(jīng)消耗完了要么授權(quán)狀態(tài)還沒來得及同步。第一次遇到建議先等幾秒重試一次還不行就查授權(quán)庫存。5.2 審核合規(guī)紅線這些操作一碰就涼訂閱消息最大的合規(guī)紅線是誘導(dǎo)授權(quán)。公眾號后臺審核時會重點檢查你的頁面有沒有訂閱有禮開啟通知送優(yōu)惠券這類誘導(dǎo)話術(shù)。微信對誘導(dǎo)用戶開啟訂閱的行為定性很明確一旦發(fā)現(xiàn)輕則模板被清退重則封禁消息推送接口。我親眼見過一個項目把訂閱彈窗和紅包活動綁定用戶點允許才能領(lǐng)紅包上線第二天模板就被封了。微信的邏輯很簡單訂閱授權(quán)必須是用戶自愿的、出于真實需求的操作不能跟利益掛鉤。另外模板的使用場景要和用戶動作保持一致。你在訂單發(fā)貨模板里推送廣告內(nèi)容第一次可能沒事被用戶舉報后微信會倒查到時候整個后臺的訂閱消息功能都可能被限制。推送內(nèi)容務(wù)必和模板聲明的場景強(qiáng)綁定。5.3 我踩過的坑和一些實測心得開發(fā)這大半年的小程序消息推送功能我印象最深的是三個教訓(xùn)第一個是授權(quán)彈窗頻控。有一版產(chǎn)品經(jīng)理要求每個頁面都要引導(dǎo)訂閱結(jié)果用戶從一個頁面跳到另一個頁面連續(xù)被彈了四次訂閱框。第二天測試手機(jī)就再也彈不出訂閱框了微信對用戶的保護(hù)機(jī)制直接把我們拉黑了。后來我們收斂成每個用戶生命周期最多彈三次訂閱只在最核心的業(yè)務(wù)節(jié)點觸發(fā)。第二個是 data 字段超長的問題。有個后臺配置的功能運(yùn)營人員填了超過 20 個字的商品名發(fā)送時一直報 47003前端頁面還看不到具體錯誤排查了很久才發(fā)現(xiàn)是字段長度問題。后來我在后端加了一層參數(shù)校驗超過長度直接截斷并打日志問題再也沒出現(xiàn)過。第三個是授權(quán)庫存的統(tǒng)計口徑。剛開始我們只記錄了用戶授權(quán)成功的事件忽略了發(fā)送失敗和用戶主動關(guān)閉開關(guān)的情況導(dǎo)致運(yùn)營看的數(shù)據(jù)和實際情況嚴(yán)重不符。后來把授權(quán)、消耗、失敗、關(guān)閉四種事件全部埋點才算把推送鏈路的完整數(shù)據(jù)串起來。最后一個實用技巧調(diào)試訂閱消息時建議在開發(fā)者工具里先把模擬訂閱消息的功能用起來這個功能可以讓你不用真機(jī)彈窗就能測后端發(fā)送鏈路。但注意工具模擬和真機(jī)行為存在差異比如授權(quán)彈窗的觸發(fā)時機(jī)、頻控限制這些最終還是要以真機(jī)為準(zhǔn)。我一般先用工具調(diào)通接口再上真機(jī)驗證完整鏈路兩邊配合能省不少時間。 從模板消息到訂閱消息：小程序消息推送實戰(zhàn)避坑指南
微信小程序做消息推送前前后后折騰了大半年從最開始的模板消息一路踩到訂閱消息中間被各種文檔坑得夠嗆。今天把這段經(jīng)驗完整整理出來標(biāo)題就叫從模板消息到訂閱消息的實戰(zhàn)避坑指南——這不僅僅是接口替換的問題整個推送體系的思路都變了。如果你正準(zhǔn)備給自己的小程序接入推送或者正在被用戶授權(quán)了為什么還是發(fā)不出去折磨這篇文章應(yīng)該能幫你少走不少彎路。先說結(jié)論消息推送這事方案選型比代碼實現(xiàn)重要得多。微信把模板消息砍掉、全面轉(zhuǎn)向訂閱消息本質(zhì)上是把推送主動權(quán)從開發(fā)者手里拿回來一部分交給用戶。你可以在用戶每次操作后請求一次訂閱授權(quán)攢夠了授權(quán)額度再定向推送。這套機(jī)制看起來簡單但實際跑起來會發(fā)現(xiàn)授權(quán)時機(jī)、額度消耗、模板字段、調(diào)試環(huán)境這些環(huán)節(jié)處處是坑。1. 先把規(guī)則吃透模板消息為什么退場訂閱消息到底怎么運(yùn)作1.1 模板消息退場的真實原因不是技術(shù)不行是容易騷擾用戶老開發(fā)者應(yīng)該都記得模板消息的流程用戶在小程序里完成一次操作后彈窗征求用戶同意同意后開發(fā)者就能在后續(xù)任意時間點給用戶推送模板消息而且推送次數(shù)不受嚴(yán)格限制。我早期的項目就是靠這個做訂單狀態(tài)通知的體驗確實方便用戶只要授權(quán)一次后面發(fā)貨、簽收、售后每個節(jié)點都能推。但問題恰恰出在授權(quán)一次永久使用上。很多小程序把模板消息當(dāng)免費(fèi)短信用用戶稍微有點互動就狂推營銷內(nèi)容最終結(jié)果就是用戶被騷擾到直接把小程序的通知權(quán)限關(guān)了。微信官方后來把模板消息逐步下線新注冊的小程序后臺已經(jīng)看不到模板消息入口老接口也在 2020 年初徹底停用。本質(zhì)原因就一句話這種授權(quán)模式?jīng)]法約束開發(fā)者必須改成一次授權(quán)、一次推送的單次消耗模型這就是訂閱消息的雛形。1.2 訂閱消息的規(guī)則核心授權(quán)一次只能推一條訂閱消息最核心的規(guī)則就一句用戶的每次允許授權(quán)只對應(yīng)一次消息推送的額度。用戶點了允許你拿到一條推送額度用掉之后想再推必須讓用戶再次授權(quán)。這個設(shè)計意味著你不能像以前那樣先囤授權(quán)再慢慢推而要把推送動作和用戶的具體操作強(qiáng)綁定。比如用戶下單成功后你彈訂閱框拿到額度后立刻發(fā)送下單成功通知這就是最標(biāo)準(zhǔn)的一次消耗閉環(huán)。如果你想在發(fā)貨時再推一條就要在用戶下單時多次彈窗請求授權(quán)或者等到發(fā)貨前再找機(jī)會觸發(fā)授權(quán)彈窗。很多第一次做訂閱消息的開發(fā)者會習(xí)慣性地問用戶每點一次允許我只能推一條那我的業(yè)務(wù)有五個節(jié)點需要通知怎么辦答案只有一個你的業(yè)務(wù)需要在不同的用戶動作節(jié)點上分別去拿對應(yīng)的授權(quán)。比如下單節(jié)點拿下單成功通知的授權(quán)發(fā)貨節(jié)點拿發(fā)貨提醒的授權(quán)每一個節(jié)點獨立授權(quán)、獨立消耗。1.3 一次性訂閱和長期訂閱別再混為一談了訂閱消息分為兩種一次性訂閱消息和長期訂閱消息。一次性訂閱消息是目前絕大多數(shù)小程序都在用的類型任何主體都能申請用戶每次授權(quán)對應(yīng)一條推送額度。長期訂閱消息則完全不同。它允許開發(fā)者一次授權(quán)后在用戶沒有再次操作的情況下多次推送但它對行業(yè)類目有嚴(yán)格限制僅限醫(yī)療、政務(wù)、金融、教育等民生服務(wù)領(lǐng)域個人主體和絕大多數(shù)普通企業(yè)主體根本沒資格申請。我在后臺翻過類目列表普通電商、工具類目基本找不到長期訂閱的入口。所以對大部分開發(fā)者來說只需要無腦關(guān)注一次性訂閱消息就行。如果有人在技術(shù)社區(qū)跟你說我這里可以開通長期訂閱基本可以斷定是違規(guī)代開通或者營銷騙局微信對這種灰色操作的打擊力度很大不要碰。2. 前端實戰(zhàn)授權(quán)鏈路從 openid 開始2.1 openid 從哪來code 換 openid 的基礎(chǔ)流程不能錯訂閱消息推送時后端必須知道接收者的 openid這個 openid 是每個用戶在每個小程序下的唯一標(biāo)識。獲取 openid 的標(biāo)準(zhǔn)姿勢就是 wx.login 拿 code然后后端拿著 code 換 openid 和 session_key。前端只有一小段代碼// 前端用戶進(jìn)入小程序時執(zhí)行 wx.login({ success(res) { if (res.code) { // 把 code 傳給后端 wx.request({ url: https://your-api.com/api/login, data: { code: res.code }, success(result) { // 后端返回 openid前端可以存起來備用 console.log(result.data.openid) } }) } } })后端拿到 code 后調(diào)微信的 jscode2session 接口GET https://api.weixin.qq.com/sns/jscode2session?appidAPPIDsecretAPPSECRETjs_codeCODEgrant_typeauthorization_code注意兩個坑第一這個接口用的是 appid 加 secret不需要 access_token很多人會下意識以為所有微信接口都要帶 access_token結(jié)果在這里先卡一道第二code 有效期只有 5 分鐘而且只能用一次用完作廢。我之前排過一個線上問題前端并發(fā)請求把同一個 code 用了兩次第二次直接報 invalid code排查了半天才發(fā)現(xiàn)是重復(fù)消費(fèi)了。換回來的結(jié)果是一個 JSON包含 openid 和 session_key。openid 建議在后端直接和用戶體系綁定不要反復(fù)通過前端傳來傳去避免被偽造。2.2 授權(quán)彈窗的正確喚起姿勢別在 onLoad 里瞎彈wx.requestSubscribeMessage 是前端拉起訂閱授權(quán)彈窗的接口但它的調(diào)用時機(jī)非常有講究。最基礎(chǔ)的規(guī)則是必須在用戶點擊行為tap的同步回調(diào)里調(diào)用不能在 onLoad、onShow 這些生命周期里直接彈否則在某些基礎(chǔ)庫版本下會出現(xiàn)接口調(diào)用成功但彈窗死活不出來的情況或者被微信靜默降級處理。更深一層的問題是頻控。如果用戶在一段時間內(nèi)被你反復(fù)彈窗詢問訂閱微信會直接限制你的彈窗喚起權(quán)限。我實測下來的體感是同一用戶同一模板短時間內(nèi)彈兩次以上第二次彈窗出來的概率就明顯下降如果用戶連續(xù)拒絕兩三次后面基本就彈不出來了。所以正確做法是不要在頁面加載時就請求訂閱而要把訂閱動作綁定到真實的業(yè)務(wù)操作節(jié)點上。比如下單成功、支付完成、報名成功這些用戶主動完成動作的按鈕回調(diào)里順勢彈出訂閱框。用戶剛完成一個動作心理預(yù)期里確實需要收到后續(xù)通知這時候彈窗的接受率最高。2.3 前端實操代碼一個干凈的訂閱按鈕示例下面這個示例是支付成功后引導(dǎo)用戶訂閱訂單狀態(tài)通知的標(biāo)準(zhǔn)寫法。// 支付成功回調(diào)里觸發(fā)訂閱 function handlePaySuccess(orderId) { // 先做業(yè)務(wù)請求再拉起訂閱 wx.requestSubscribeMessage({ tmplIds: [TEMPLATE_ID_HERE], // 在 mp 后臺申請到的模板 ID success(res) { // 返回結(jié)果是一個對象key 是模板 ID if (res[TEMPLATE_ID_HERE] accept) { // 用戶點了允許拿到一條推送額度 // 把授權(quán)結(jié)果上報后端由后端記錄授權(quán)庫存 reportSubscribeAuth(orderId, TEMPLATE_ID_HERE) } else if (res[TEMPLATE_ID_HERE] reject) { // 用戶拒絕不要反復(fù)彈 console.log(用戶拒絕了訂閱) } else if (res[TEMPLATE_ID_HERE] ban) { // 被微信限制彈窗需要引導(dǎo)用戶去設(shè)置頁手動開啟 console.log(訂閱被限制) } }, fail(err) { // 彈窗喚起失敗常見原因是調(diào)用時機(jī)不對或頻控 console.error(訂閱調(diào)用失敗, err) } }) }重點說一下返回值的判斷。wx.requestSubscribeMessage 的 success 回調(diào)里返回值是一個以模板 ID 為 key 的對象value 有三種情況accept 表示允許、reject 表示拒絕、ban 表示被限制。很多人只判斷了 success 就默認(rèn)用戶一定允許了這是不嚴(yán)謹(jǐn)?shù)?。必須根?jù)模板 ID 逐個取 value再看是不是 accept。另外 tmplIds 參數(shù)一次最多傳 3 個模板 ID這是官方限制。但我實際測試下來一次彈 3 個模板的轉(zhuǎn)化率會明顯下降用戶看到三連彈窗往往直接全拒。我的建議是一個業(yè)務(wù)節(jié)點只彈一個最相關(guān)的模板寧可多設(shè)計幾個觸發(fā)節(jié)點也別在一個彈窗里塞多個模板。3. 后端發(fā)送access_token、模板字段與接口調(diào)試3.1 access_token 的緩存策略別每次都去換會被限流后端發(fā)送訂閱消息前必須拿到 access_token這是調(diào)用所有微信 cgi-bin 接口的通行證。access_token 的有效期是 7200 秒兩小時每次獲取都有頻率限制每日獲取上限是 2000 次。如果用戶量稍微上來一點每次發(fā)送都現(xiàn)取 token很容易把 2000 次配額打爆接著就會報 45009接口調(diào)用超過限額。我比較推薦的做法是內(nèi)存緩存加過期時間JVM 或 Node 進(jìn)程里掛一個定時刷新任務(wù)提前 5 分鐘把 token 續(xù)上。偽代碼如下let cachedToken null let tokenExpireTime 0 async function getAccessToken() { // 提前 5 分鐘刷新避免邊緣過期 if (cachedToken tokenExpireTime - 300 Date.now()) { return cachedToken } const url https://api.weixin.qq.com/cgi-bin/token?grant_typeclient_credentialappid${APPID}secret${APPSECRET} const res await axios.get(url) cachedToken res.data.access_token tokenExpireTime Date.now() res.data.expires_in * 1000 return cachedToken }如果是多實例部署建議把 token 放到 Redis 里加鎖更新避免多個實例同時去刷新導(dǎo)致 token 互相覆蓋。這一點在線上環(huán)境很重要我見過測試環(huán)境單機(jī)跑著沒事一上生產(chǎn)多實例部署立刻出現(xiàn) 40001 的案例原因就是各實例各自緩存了不同的 token后一個獲取的把前一個頂?shù)袅恕?.2 訂閱消息發(fā)送接口Node.js 完整示例發(fā)送訂閱消息的接口是POST https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_tokenACCESS_TOKEN請求體是一個 JSON{ touser: OPENID, template_id: TEMPLATE_ID, page: pages/order/detail?id123, miniprogram_state: formal, lang: zh_CN, data: { thing1: { value: 您的訂單已發(fā)貨 }, time2: { value: 2024年6月30日 15:00 }, character_string3: { value: SF1234567890 } } }對應(yīng) Node.js 后端代碼const axios require(axios) async function sendSubscribeMessage(openid, templateId, data, page) { const token await getAccessToken() const url https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_token${token} const body { touser: openid, template_id: templateId, page: page || pages/index/index, miniprogram_state: formal, lang: zh_CN, data } const res await axios.post(url, body) if (res.data.errcode 0) { // 發(fā)送成功同時消耗一條用戶授權(quán)額度 return { success: true } } else { // 發(fā)送失敗根據(jù) errcode 做不同處理 return { success: false, errcode: res.data.errcode, errmsg: res.data.errmsg } } }這里有一個很多新手會卡住的點miniprogram_state 參數(shù)。它有三個可選值developer開發(fā)版、trial體驗版、formal正式版。如果你當(dāng)前測試的小程序是體驗版但 miniprogram_state 傳了 formal接口可能返回成功但用戶手機(jī)上根本收不到這條訂閱消息。反過來也一樣正式版環(huán)境用 developer 也收不到。正確的測試姿勢是開發(fā)調(diào)試時用 developer 或 trial發(fā)布上線后用 formal。我當(dāng)時就是在體驗版環(huán)境測試忘了改這個參數(shù)結(jié)果后端日志顯示發(fā)送成功手機(jī)一直收不到排查了一個下午才發(fā)現(xiàn)是環(huán)境狀態(tài)不匹配。3.3 data 字段匹配模板字段的類型和長度限制訂閱消息的 data 字段是最容易報 47003參數(shù)格式錯誤的地方。你在 mp 后臺申請模板時模板里每個字段都有固定的 key比如 thing1、time2、number3、character_string4 這些。data 里的 key 必須和模板字段完全一致少一個、多一個、key 名寫錯都會直接報錯。每種字段類型對 value 的格式和長度都有硬性限制thing20 個以內(nèi)漢字適合放物品名、訂單備注等文本number數(shù)字類型適合放金額、數(shù)量time時間格式需要按指定格式傳一般是2024年6月30日 15:00這種樣式character_string20 個以內(nèi)字符適合放訂單號、快遞單號phrase5 個以內(nèi)漢字適合放一句話狀態(tài)我踩過最深的坑是 thing 和 phrase 的長度限制。開發(fā)時測試數(shù)據(jù)短沒事一上線用戶輸入長一點就直接報 47003。有個比較穩(wěn)妥的處理后端在組裝 data 之前先對每個字段做長度截斷或校驗超長的給用戶提示別讓臟數(shù)據(jù)打到微信接口。4. 從模板消息遷移到訂閱消息一份改造清單4.1 模板 ID 的變化從老接口到新模板 ID模板消息時代模板 ID 一般是一串很長的數(shù)字加字母混合的值訂閱消息的模板 ID 則是 T 字母開頭的一串字符。你在 mp 后臺的訂閱消息模塊里申請模板審核通過后就能拿到 T 開頭的模板 ID。申請的路徑是登錄微信公眾平臺 → 功能 → 訂閱消息 → 公共模板庫 → 選類目 → 選關(guān)鍵詞 → 組合成自定義模板。關(guān)鍵詞是從該行業(yè)類目下的固定詞庫里選的不能自己隨意造詞。比如電商類目下會有訂單發(fā)貨提醒物流簽收通知這些關(guān)鍵詞可用。申請審核一般比較快快的時候幾小時就過了慢的話一到兩個工作日。我建議提前把業(yè)務(wù)需要的模板一次性申請好別等上線了再補(bǔ)審核期間業(yè)務(wù)會卡住。從模板消息遷移到訂閱消息時你舊的后端邏輯里所有調(diào)用模板消息發(fā)送接口的地方都要換成訂閱消息接口模板 ID 全部替換授權(quán)邏輯也要重寫。相比代碼改動業(yè)務(wù)邏輯的調(diào)整更關(guān)鍵模板消息是一次授權(quán)無限推送訂閱消息是一次授權(quán)一條推送你的推送節(jié)點設(shè)計、授權(quán)觸發(fā)時機(jī)全都要重新規(guī)劃。4.2 授權(quán)庫存管理把每條授權(quán)當(dāng)成一種資產(chǎn)訂閱消息的授權(quán)額度是稀缺資源不能隨用隨丟。我建議后端建一張表專門記錄授權(quán)和消耗情況用戶 openid模板 ID授權(quán)時間是否已消耗消耗時間關(guān)聯(lián)的業(yè)務(wù)單號用戶在哪個業(yè)務(wù)節(jié)點授權(quán)了哪個模板額度是否已經(jīng)用來發(fā)送過消息都要能隨時查出來。后面如果用戶投訴我沒授權(quán)怎么給我推消息你可以直接拉出這張表自證清白。這里涉及一個關(guān)鍵的消費(fèi)邏輯當(dāng)你調(diào)用發(fā)送接口返回 errcode 0 之后微信默認(rèn)消耗了用戶的一次授權(quán)。如果返回的是 43101用戶拒絕說明當(dāng)前沒有可用授權(quán)額度這次發(fā)送不消耗任何額度。但要注意一種特殊情況用戶剛在前端點完允許你立刻在后端發(fā)消息有一定概率仍然返回 43101因為微信服務(wù)端對授權(quán)狀態(tài)的寫入存在輕微延遲。我的解決辦法是授權(quán)后不立即發(fā)送而是把發(fā)送任務(wù)丟進(jìn)延遲隊列等 5 到 10 秒再發(fā)實測能把 43101 的概率降到很低。4.3 提高送達(dá)率的三個手段別只會調(diào)接口訂閱消息能不能真正到達(dá)用戶手機(jī)接口返回成功只是第一步用戶是否愿意點開、是否愿意繼續(xù)授權(quán)才是關(guān)鍵。第一授權(quán)彈窗的時機(jī)要貼近用戶真實需求。下單成功后問要不要接收發(fā)貨提醒通過率很高用戶剛打開首頁就彈允許我們給你推送消息基本是找拒。把訂閱動作嵌到業(yè)務(wù)流程里而不是做成獨立環(huán)節(jié)。第二推送內(nèi)容要一條是一條。訂閱消息的本質(zhì)是服務(wù)通知不是營銷短信。模板里能放的字?jǐn)?shù)有限你更應(yīng)該確保每條消息對用戶有實際價值。我見過一個電商項目用戶一注冊就被彈訂閱彈窗通過率不到 10%后來改成支付完成頁彈發(fā)貨通知通過率直接翻倍。第三要關(guān)注用戶主動關(guān)閉通知的情況。用戶在小程序右上角的...菜單里可以關(guān)閉整個小程序的服務(wù)通知開關(guān)關(guān)閉后你發(fā)訂閱消息接口照樣返回成功但用戶收不到。這不是技術(shù)能解決的只能靠內(nèi)容質(zhì)量把用戶求回來。5. 高頻報錯排查與避坑實錄5.1 高頻報錯速查表這里整理了我實際開發(fā)中遇到的幾個高頻錯誤碼建議大家收藏備查錯誤碼錯誤含義排查思路40001access_token 無效或過期檢查 token 緩存邏輯是否多實例互相覆蓋重新獲取40003openid 不正確確認(rèn) openid 是否來自同一小程序前后端環(huán)境是否一致40037模板 ID 不正確確認(rèn)模板 ID 是否 T 開頭是否在后臺申請通過41030page 路徑不正確page 必須以 pages/ 開頭且在 app.json 中注冊43101用戶拒絕接受消息授權(quán)額度已消耗或用戶拒絕了授權(quán)檢查授權(quán)庫存47003參數(shù)格式錯誤檢查 data 字段 key、value 類型和長度限制45009接口調(diào)用超過限額access_token 是否做了緩存是否觸發(fā)微信頻控43101 是大家遇到最多的錯誤但它的原因其實就那么幾個要么用戶確實拒絕了彈窗要么額度已經(jīng)消耗完了要么授權(quán)狀態(tài)還沒來得及同步。第一次遇到建議先等幾秒重試一次還不行就查授權(quán)庫存。5.2 審核合規(guī)紅線這些操作一碰就涼訂閱消息最大的合規(guī)紅線是誘導(dǎo)授權(quán)。公眾號后臺審核時會重點檢查你的頁面有沒有訂閱有禮開啟通知送優(yōu)惠券這類誘導(dǎo)話術(shù)。微信對誘導(dǎo)用戶開啟訂閱的行為定性很明確一旦發(fā)現(xiàn)輕則模板被清退重則封禁消息推送接口。我親眼見過一個項目把訂閱彈窗和紅包活動綁定用戶點允許才能領(lǐng)紅包上線第二天模板就被封了。微信的邏輯很簡單訂閱授權(quán)必須是用戶自愿的、出于真實需求的操作不能跟利益掛鉤。另外模板的使用場景要和用戶動作保持一致。你在訂單發(fā)貨模板里推送廣告內(nèi)容第一次可能沒事被用戶舉報后微信會倒查到時候整個后臺的訂閱消息功能都可能被限制。推送內(nèi)容務(wù)必和模板聲明的場景強(qiáng)綁定。5.3 我踩過的坑和一些實測心得開發(fā)這大半年的小程序消息推送功能我印象最深的是三個教訓(xùn)第一個是授權(quán)彈窗頻控。有一版產(chǎn)品經(jīng)理要求每個頁面都要引導(dǎo)訂閱結(jié)果用戶從一個頁面跳到另一個頁面連續(xù)被彈了四次訂閱框。第二天測試手機(jī)就再也彈不出訂閱框了微信對用戶的保護(hù)機(jī)制直接把我們拉黑了。后來我們收斂成每個用戶生命周期最多彈三次訂閱只在最核心的業(yè)務(wù)節(jié)點觸發(fā)。第二個是 data 字段超長的問題。有個后臺配置的功能運(yùn)營人員填了超過 20 個字的商品名發(fā)送時一直報 47003前端頁面還看不到具體錯誤排查了很久才發(fā)現(xiàn)是字段長度問題。后來我在后端加了一層參數(shù)校驗超過長度直接截斷并打日志問題再也沒出現(xiàn)過。第三個是授權(quán)庫存的統(tǒng)計口徑。剛開始我們只記錄了用戶授權(quán)成功的事件忽略了發(fā)送失敗和用戶主動關(guān)閉開關(guān)的情況導(dǎo)致運(yùn)營看的數(shù)據(jù)和實際情況嚴(yán)重不符。后來把授權(quán)、消耗、失敗、關(guān)閉四種事件全部埋點才算把推送鏈路的完整數(shù)據(jù)串起來。最后一個實用技巧調(diào)試訂閱消息時建議在開發(fā)者工具里先把模擬訂閱消息的功能用起來這個功能可以讓你不用真機(jī)彈窗就能測后端發(fā)送鏈路。但注意工具模擬和真機(jī)行為存在差異比如授權(quán)彈窗的觸發(fā)時機(jī)、頻控限制這些最終還是要以真機(jī)為準(zhǔn)。我一般先用工具調(diào)通接口再上真機(jī)驗證完整鏈路兩邊配合能省不少時間。