UNI-APP/VUE 项目集成微信SDK教程和避坑指南

文章同步发布于🚀前端知识营地,移动端用户可通过🐱‍🏍手机端查看以获得更佳的阅读体验和排版效果

前言

  • 本文主要介绍在UNI-APP项目中集成 微信SDK / 微信开放标签 。由于UNI-APP是对Vue 的二次封装,因此本教程也适用与Vue项目。
  • 本项目是基于已经认证的微信服务号(是服务号不是微信公众号/订阅号)进行开发,根据官方文档微信公众号也是可以集成SDK的,但是微信开放标签,目前主要是跳转到小程序跳转到APP 都是需要已经认证的服务号才可调用,由于跳转到APP需要前往微信开放平台的管理中心-公众账号或小程序详情-接口信息-网页跳转移动应用-关联设置中绑定所需要跳转的App。本文暂未具备条件,下文仅说明说和适用开放标签跳转到微信小程序。具体细节还请参考微信官方的开发文档🚀微信公众号网页开发文档

先行条件

由于微信各方面要求严格,因此在开发前需要自检自己是否具备集成微信SDK/微信开放标签的先决条件。根据本人的开发经历,在开发集成之前需要具备的先行条件如下:

  1. 拥有自己的服务器

主要是用于安全认证和绑定JS接口安全域名

  1. 已经完成认证的微信服务号,以便使用开放标签

如果仅集成SDK,根据官方文档说明,好像微信公众号也可以,具体是否可行,有待读者验证

  1. 良好的心态

嗯!微信的文档你懂的,以及微信各种出于安全的限制让开发调试异常麻烦,因此一个良好的心态异常重要

  1. 满足微信官方的配置要求

微信开放标签有最低的微信版本要求,以及最低的系统版本要求。
微信版本要求为:7.0.12及以上。 系统版本要求为:iOS 10.3及以上、Android 5.0及以上。

  • 以上条件若有不满足的,请出门右拐

集成微信SDK

使用微信开放标签之前需要先完成SDK集成,因此,本文先介绍如何集成微信SDK

  • 重要提示: 请不要上来就开始写代码,请一定按照步骤一步一步完成相关配置。
步骤一:绑定JS接口安全域名

这一部操作比较简单,跟着截图操作即可

  1. 进入公众号,通过左侧设置按钮,进入公众号设置或者点击公众号昵称,在弹出菜单中点击进入功能设置。
    在这里插入图片描述在这里插入图片描述
  2. 找到JS接口安全域名,点击右侧设置进入配置
    在这里插入图片描述
  3. 按照要求填写安全域名地址,填写好域名之后,请下载验证文件MP_verify_********并将其上传到对应服务器的根目录。
    后文获取签名时传递的url必须在此域名下

在这里插入图片描述

步骤二:引入微信SDK对应的JS文件

官方介绍如下:

  • 在需要调用JS接口的页面引入如下JS文件,(支持https):http://res.wx.qq.com/open/js/jweixin-1.6.0.js
  • 如需进一步提升服务稳定性,当上述资源不可访问时,可改访问:http://res2.wx.qq.com/open/js/jweixin-1.6.0.js (支持https)。
  • 备注:支持使用 AMD/CMD 标准模块加载方法加载

如果你根据官方介绍不知道怎么操作,或者引入后结果不正确,请继续查阅本文介绍:

在 Vue 项目下引入微信SDK有如下几种方法:

  1. 访问http://res.wx.qq.com/open/js/jweixin-1.6.0.js 直接间代码拷贝到本地,然后在使用的页面中引入。
  2. 使用npm安装jweixin-modulejweixin-module其实就是将微信SDK的源代码发布到了npm上,因此这种方式和方法1是一样的。
  3. 在页面中创建script标签,通过script引入。

方法3,需要操作DOM并创建script元素,这里不推荐,方法2和方法1原理和效果相同,这里就以方法2介绍,如何引入微信SDK,毕竟同一个世界,同一个NPM!

  1. 安装jweixin-module
	npm install jweixin-module --save  
  1. 在项目合适的位置创建wx-js-sdk.js文件,通常将此类文件放到utils文件夹下。
		// 引入 jweixin-module
		const jweixin = require('jweixin-module')// 通过export 暴露常用的方法
		export default {
 			 //判断是否在微信中    
		   isWechat: function () {
			  var ua = window.navigator.userAgent.toLowerCase();
			    if (ua.match(/micromessenger/i) == 'micromessenger') {
			      //console.log('是微信客户端')  
			      return true;
			    } else {
			      //console.log('不是微信客户端')  
			      return false;
			    }
			},

			// 初始化WXSDK
		  initJssdk: async function (callback) {
		     /* ****************************************
		      * 获取当前url然后传递给后台获取授权和签名信息
		      # TODO: 后台返回签名
		      *************************************** */  
		    // let uri = encodeURIComponent(window.location.href.split('#')[0]);
		    let uri = window.location.href.split('#')[0];
		
		    //返回需要的参数appId,timestamp,noncestr,signature等  
		    let timestamp = parseInt(new Date().getTime() / 1000) + '';
		    let nonceStr = Math.random().toString(36).substr(2, 15);

			// 获取后台返回的签名
			// 这里需要换成开发者自己的接口。
			// 此处我对uni.request进行了封装,
			// 直接采用uni.request方法然后在成功的回调里面完成SDK初始化也是可行的,根据实际情况处理
		    let res = await GetSignature(nonceStr,timestamp,uri);  
		    
   			 //注入config权限配置  
		    let wxConf = {
		      debug: false,  // 是否开启调试,第一次尝试,建议开启,后续可关闭
		      openTagList:['wx-open-launch-weapp'],  //使用的开放标签列表,目前就两,本项目只用到跳转到小程序
		      appId:"your_appid",  // 公众号或者服务号的appid,自行前往服务号管理后台查看
		      timestamp,  // 上文计算的时间戳
		      nonceStr,    // 随机字符串,注意是小驼峰式写法
		      signature:res,  // 回台返回的签名
		      jsApiList: [ //这里是需要用到的接口名称  
		        'checkJsApi', //判断当前客户端版本是否支持指定JS接口  
		        'onMenuShareAppMessage', //分享接口  
		        'getLocation', //获取位置  
		        'openLocation', //打开位置  
		        'scanQRCode', //扫一扫接口  
		        'chooseWXPay', //微信支付  
		        'chooseImage', //拍照或从手机相册中选图接口  
		        'previewImage', //预览图片接口  
		        'uploadImage' //上传图片  
		      ]
		    };
		    jweixin.config(wxConf);   //完成微信配置
		  },
		  
		  /* ***************************************
		   *
		   *   微信SDK功能实例:调用微信扫码
		   *  若没有初始化需要先调用initJssdk完成初始化
		   *  若当前页面已经完成initJssdk初始化,调用扫码功能是可以直接调用 jweixin.scanQRCode
		   * 
		   * **************************************/
		 scanCode:function(callback,needResult=1){
		    if (!this.isWechat()) {
		      console.log('不是微信客户端')  
		      return;
		    }
		    this.initJssdk(function (res) {
		      jweixin.ready(function () {
		        jweixin.scanQRCode({
		          needResult: needResult, // 0扫码结果由微信处理, 1是直接返回结果,由开发者处理
		          scanType: ["qrCode","barCode"],
		          success: function (rs) {
		            console.log(rs);
		            callback(rs)
		          }
		        })
		      });
		    });
		  }
		}
  • 扫码部分的代码来源自网络分享,仅供参考,在真实使用的时候同一个URL下SDK只需初始化一次即可,向上面这样的写法,每次调用扫码接口都要进行SDK初始化显然不够友好。
  • 比较好的做法是,在相同的页面中比如mounted生命周期里仅调用initJssdk初始化一次。然后直接使用jweixin.scanQRCode,就像下面这样。具体用法后续再介绍。
methods:{
	scan(needResult){
   		jweixin.scanQRCode({
         	  needResult: needResult, // 0扫码结果由微信处理, 1是直接返回结果,由开发者处理
        	  scanType: ["qrCode","barCode"],
        	  success: function (rs) {
         		   console.log(rs);
         		   // 干点啥呗!
         	  }
   	    })
   }

}
步骤三: 在具体页面引入步骤2创建的wx-js-sdk.js文件,并执行initJssdk初始化
  • 全局初始化(uni-app项目): 在APP.vue中执行初始化。

Vue / UNI-APP 项目也可以直接在main.js中执行初始化

<script>
	import wxJsSdk from '@/utils/wx-js-sdk';
	export default {
		onLaunch: function() {
			if(!this.ISWX){ //不是微信环境
				// 不是微信环境怎么办呢?
			}
			else{
				// 初始化WXSDK
				wxJsSdk.initJssdk();
			}
		},
		onShow: function() {

		},
		onHide: function() {

		}
	}
</script>
  • 页面初始化 :在具体页面中引入并初始化
<script>
	import wxJsSdk from '@/utils/wx-js-sdk';
	export default {
		mounted() {
			wxJsSdk.initJssdk();
		},
	}
</script>
步骤四:功能测试
<script>
	import wxJsSdk from '@/utils/wx-js-sdk';
	const jweixin = require('jweixin-module'); // 引入SDK,参考微信官方文档调用各开放接口
	export default {
		mounted() {
			wxJsSdk.initJssdk();
		},
		 methods:{
		 	scan(needResult){
					jweixin.scanQRCode({
			      	  needResult: needResult, // 0扫码结果由微信处理, 1是直接返回结果,由开发者处理
			     	  scanType: ["qrCode","barCode"],
			     	  success: function (rs) {
			      		   console.log(rs);
			      		   // 干点啥呗!
			      	  }
				    })
			}

		}
	}
</script>
  • 将本地调试地址,粘贴到微信开发者工具/公众号网页调试模式下,访问调试地址如:http://192.168.1.9:8080/wxsdk/,此时控制台打印如下错误在这里插入图片描述
    遇到错误,不要慌!!!,40048错误说明你当前用于获取签名的url不在步骤一所在的安全域名下,这个时候需要将项目打包并部署到步骤一配置的安全域名对应的服务器上,然后再通过控制台访问,此时控制台打印如下信息,同时调用扫码接口也返回了ok。至此说明微信SDK集成成功。通过真机访问,可以拉起微信扫码,并返回扫描结果。
    在这里插入图片描述
避坑指南

通过上述步骤,已经完成了在Vue/UNI-APP项目中集成微信SDK,这里有几个常见问题,大家需要注意,如果根据上面的介绍无法实现扫码功能,请查看,是否有下属问题.

  1. 检查获取的当前页面的URL是否正确,本项目通过如下代码获取到当前页面的URL,不含#及其后面部分,注意注释掉的语句,这是不正确的写法,不要被网上的文档误导.

确认url是页面完整的url(请在当前页面alert(location.href.split('#')[0])确认),包括http(s)://部分,以及?后面的GET参数部分,但不包括#hash后面的部分。

 // vue 项目,hash模式
 // let uri = encodeURIComponent(window.location.href.split('#')[0]);
 let uri = window.location.href.split('#')[0];
  1. 检查签名是否正确: 这里我的实现方式如下,前端获取随机字符串和时间戳可以参考如下写法.同时前端需将时间戳/随机字符串/当前页面url等传给后端,由后端实现签名算法并返回签名,可通过下方地址检验签名是否正确.

🚀签名校验地址

	   let uri = window.location.href.split('#')[0];
	
	   //返回需要的参数appId,timestamp,noncestr,signature等  
	   let timestamp = parseInt(new Date().getTime() / 1000) + '';
	   let nonceStr = Math.random().toString(36).substr(2, 15);
	
		// 获取后台返回的签名
		// 这里需要换成开发者自己的接口。
		// 此处我对uni.request进行了封装,
		// 直接采用uni.request方法然后在成功的回调里面完成SDK初始化也是可行的,根据实际情况处理
	   let res = await GetSignature(nonceStr,timestamp,uri);  
  1. 是否在页面中执行initJssdk初始化,若没有请参考教程在合适的地方进行初始化.
  2. 当前项目是否已经部署到安全域名对应的服务器上,若不是请打包部署.
  3. 微信公众号的appid是否正确

(未完,微信开放标签的使用请见下一篇文章)


最近一直在作微信公众号的开发,自己也申请了一个公众号,刚开始弄,主要是分享作者从各个平台收集的前端优质文章,优质教程和工具; 以知识小报的形式周更,避免打扰! 有感兴趣的同好可以扫码关注下
🚀查看前端知识营地介绍
在这里插入图片描述

Logo

前往低代码交流专区

更多推荐