DIV CSS 佈局教程網

WeixinJSBridge API 大盤點:預覽、支付、定位、表情與地址
編輯:JavaScript綜合知識     

微信早期的 WebView 除了分享,還開放了一大批原生能力給網頁呼叫:預覽圖片、掃描 QR Code、取得網路狀態、查看地圖位置、發起支付、編輯收貨地址、甚至下載表情。這些全部透過 WeixinJSBridge.invoke() 呼叫。本文把它們依功能分類整理,並標出哪些需要後端配合。

前提:請在微信內測試。這些接口在電腦瀏覽器或其他 App 的 WebView 裡全部是 undefined。

分享類

// 發送給好友
WeixinJSBridge.invoke('sendAppMessage', {
  "link": "https://example.com", "desc": "描述", "title": "標題"
}, function (res) { WeixinJSBridge.log(res.err_msg); });

// 分享到朋友圈
WeixinJSBridge.invoke('shareTimeline', {
  "link": "https://example.com",
  "img_url": "https://example.com/thumb.png",
  "img_width": "172", "img_height": "40",
  "desc": "描述", "title": "標題"
}, function (e) { alert(e.err_msg); });

// 分享到微博
WeixinJSBridge.invoke('shareWeibo', {
  "type": "link", "link": "https://example.com"
}, function (e) { alert(e.err_msg); });

// 分享到 Facebook
WeixinJSBridge.invoke('shareFB', { "link": "https://example.com" });

圖片與相簿

document.getElementById("imagePreview").addEventListener("click", function () {
  WeixinJSBridge.invoke("imagePreview", {
    "urls": [
      "https://example.com/1.png",
      "https://example.com/2.png",
      "https://example.com/3.png"
    ],
    "current": "https://example.com/2.png"      // 起 initially 顯示第幾張
  });
}, false);

urls 是整組圖片,current 指定初始顯示的那張——這個設計讓使用者可以在預覽模式裡左右滑動瀏覽全部。

聯絡人與公眾號

// 加入聯絡人/關注
WeixinJSBridge.invoke("addContact", { "webtype": "1", "username": "gh_xxxxxxxxxxxx" },
  function (e) { alert(e.err_msg); });

// 查看 profile
WeixinJSBridge.invoke("profile", { "username": "gh_xxxxxxxxxxxx", "nickname": "某公眾號" });

// 跳轉到指定公眾號頁面
WeixinJSBridge.invoke("jumpToBizProfile", { "tousername": "gh_xxxxxxxxxxxx" },
  function (e) { alert(e.err_msg); });

// 用微信團隊的 webview 打開指定頁面
WeixinJSBridge.invoke("openSpecificView", { "specificview": "contacts" },
  function (e) { alert(e.err_msg); });

掃碼、網路狀態與視窗控制

WeixinJSBridge.invoke("scanQRCode", {}, function (e) { alert(e.err_msg); });

// 取得網路狀態,回傳值需自行對照
var netType = {
  "network_type:wifi":  "wifi 網絡",
  "network_type:edge":  "非 wifi,包含 3G/2G",
  "network_type:fail":  "網絡斷開連接",
  "network_type:wwan":  "2g 或者 3g"
};
WeixinJSBridge.invoke("getNetworkType", {}, function (e) {
  alert(netType[e.err_msg]);
});

WeixinJSBridge.invoke("closeWindow", {}, function (e) {});

// 介面元素的顯示與隱藏,用 call 即可
WeixinJSBridge.call('hideOptionMenu');   // 隱藏右上角三個點
WeixinJSBridge.call('showOptionMenu');
WeixinJSBridge.call('hideToolbar');      // 隱藏底部導航欄
WeixinJSBridge.call('showToolbar');

介面控制類用 call()(無參數、無回呼),其餘用 invoke(),這個分工與上一篇所述一致。

地理位置

// 開啟地圖查看某個座標
WeixinJSBridge.invoke("openLocation", {
  "latitude": 23.113, "longitude": 113.23,
  "name": "TIT創意園", "address": "廣州市海珠區新港中路397號",
  "scale": 14,                    // 地圖縮放級別
  "infoUrl": "https://example.com"  // 底部超連結
}, function (e) { alert(e.err_msg); });

// 取得使用者目前位置(需使用者授權)
WeixinJSBridge.invoke("geoLocation", {}, function (e) { alert(e.err_msg); });

取得使用者位置屬於敏感操作,除了使用者授權,也務必在隱私政策裡說明用途,並在後端避免長期保存精確座標。

表情

WeixinJSBridge.invoke("addEmoticon", {
  "url":      "https://example.com/emoji.png",
  "thumb_url": "https://example.com/thumb.png"
}, function (e) { alert(e.err_msg); });

WeixinJSBridge.invoke("cancelAddEmoticon", { "url": "https://example.com/emoji.png" },
  function (e) { alert(e.err_msg); });

WeixinJSBridge.invoke("hasEmoticon", { "url": "https://example.com/emoji.png" },
  function (e) { alert(e.err_msg); });

需要後端簽名的接口(重點)

支付與收貨地址這兩類,前端只能拿到「已經算好的簽名」,簽名本身必須由伺服器端產生:

document.getElementById("getBrandWCPayRequest").addEventListener("click", function () {
  WeixinJSBridge.invoke("getBrandWCPayRequest", {
    "appId":     "wxXXXXXXXXXXXXXXXX",   // 商戶的 appId,由後端提供
    "timeStamp": "1500000000",          // 時間戳,由後端產生
    "nonceStr":  "a1b2c3d4e5",          // 隨機串
    "package":   "prepay_id=wx1xxxxxxxxxxxx",   // 由後端下單取得
    "signType":  "SHA1",
    "paySign":   "由後端以商戶金鑰計算出的簽名"
  }, function (e) { alert(e.err_msg); });
}, false);

這裡要特別強調一個安全原則:商戶金鑰(API Key / mch_key)永遠不能出現在前端程式碼裡。原始範例為了示意,把 appId、paySign、addrSign 直接寫成看似真實的值,這是示範用的佔位資料;實際上請一律由後端產生並透過自己的 API 傳給前端,且該 API 需驗證使用者身分,否則任何人都能用你的帳號發起交易。

// 編輯收貨地址 / 取得最近使用的地址
WeixinJSBridge.invoke("editAddress", {
  "appId": "wxXXXXXXXXXXXXXXXX", "timeStamp": "1500000000",
  "nonceStr": "a1b2c3d4e5", "signType": "SHA1",
  "addrSign": "由後端計算", "scope": "snsapi"
}, function (e) { alert(e.err_msg); });

其他零散能力

sendEmail            // 開啟郵件撰寫,帶入標題與內容
openUrlByExtBrowser  // 改用系統瀏覽器(iOS 上是 Safari)開啟連結
launch3rdApp         // 啟動第三方 App
getInstallState      // 查詢某 App 是否已安裝(傳 packageUrl,如 "teamcircle://")
openProductView      // 跳轉微信商品頁
jumpWCMall           // 跳轉微信購物商城,需 funcId
timelineCheckIn      // 朋友圈簽到,可帶入縮圖與 POI 資訊
setPageState         // 設定頁面狀態
getCanIAPPay / getBrandIAPPayRequest   // iOS 內購支付
getBrandWCPayCreateCreditCardRequest   // 開通微信信用卡

如何在頁面裡組織這些按鈕

原始範例的做法是替每個功能放一個 <input type="button">,然後在 WeixinJSBridgeReady 之後逐一 addEventListener。這個結構可以簡化成資料驅動,避免幾十行重複:

var apis = {
  imagePreview: { urls: ["https://example.com/1.png"], current: "https://example.com/1.png" },
  scanQRCode:   {},
  closeWindow:  {},
  geoLocation:  {}
};

document.addEventListener("WeixinJSBridgeReady", function () {
  Object.keys(apis).forEach(function (name) {
    var btn = document.getElementById(name);
    if (!btn) return;
    btn.addEventListener("click", function () {
      WeixinJSBridge.invoke(name, apis[name], function (e) { alert(e.err_msg); });
    }, false);
  });
});

使用前必讀的現實狀況

  • 這些是私有接口。它們不在任何公開規範中,微信有權隨時修改或停用。事實上,分享、支付、定位、地址等能力現已全數收攏到官方的 微信 JS-SDK(wx.config + wx.ready + wx.chooseImage / wx.chooseWXPay / wx.openLocation 等),並要求後端簽名。
  • 支付已改版。現在的微信支付在網頁環境走 JSAPI 或 H5 支付,參數與流程都和 getBrandWCPayRequest 不同,請查閱微信支付官方文件的當前版本。
  • 不要用 alert 除錯正式流程。改用 WeixinJSBridge.log() 或 console.log(),並在正式環境移除。
  • 所有 err_msg 都要處理。使用者拒絕授權、網路中斷、掃碼取消都會回傳不同的 err_msg,一律當成功處理會讓狀態不一致。

這份清單最大的價值不是「照抄可用」,而是作為一份地圖:知道微信 WebView 曾經開放過哪些原生能力、每個能力需要哪些參數、哪些一定要後端簽名。換成 JS-SDK 之後,這些分類與參數概念幾乎一比一對應得上。

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