记录一下如何从0-1开发企业微信侧边栏的过程

答案answer
1,085 阅读3分钟

前言

最近因为公司新的业务需求，需要开发企业微信侧边栏的功能，由于之前没有做过这方面的一些开发，技术调研和踩坑肯定是在所难免的，本篇以我个人视角分享一下如何实现企业微信侧边栏从0-1的开发过程

1715780237875.png

准备工作

1.下载企业微信：企业微信官网

2.创建测试企业：详细教程 根据教程将需要填写的信息都填写完成就行了

3.登录企业微信后台 work.weixin.qq.com/wework_admi…

4.创建应用：选择应用管理>创建应用

image.png

image.png

应用logo和应用名称根据自己想法填就行了

5.创建成功后，需要关注的就是这个AgentId，在后续调用企业微信API中会用到这个参数

image.png

创建企业微信侧边栏

1.在配置到聊天工具栏点击配置

image.png

2.填写页面名称和页面内容

image.png

3.保存成功后将企业微信关闭在重新打开，然后选择一个微信账号对话框，就可以看到新增的侧边栏了

image.png

本地开发环境如何调试

因为企业微信侧边栏无法支持本地ip/localhost地址的访问，所以只能通过代理的方式将本地ip/localhost地址代理到一个https下的域名地址去

这里推荐使用 Whistle 去做全局代理

1.首先安装 Whistle

# 安装
npm install -g whistle

# 开启 Whistle
w2 start

2.打开命令窗口中的ip地址

image.png

3.下载https证书，下载完成之后安装即可(点击右上角HTTPS选项),具体安装路径可查看该文档（wproxy.org/whistle/web…

image.png

image.png

4.添加代理规则

image.png

代理域名：项目部署到线上的域名地址，如：你的项目是 wecom-cs.100cbc.com 那么就填写 wecom-cs.100cbc.com

端口号：http://127.0.0.1: + 前端项目的端口号如图

image.png

5.手动更改代理服务器设置（windows11电脑为例），搜索：手动更改代理服务器设置

设置代理地址为127.0.0.1 端口:8899

image.png

image.png

6.将当前电脑IP加入当前企业可信IP中

image.png

image.png 7.注意：开启电脑本地代理后可能会影响部分网站的访问和桌面软件的使用

如：csdn,和钉钉。记得在不需要本地调试后记得把代理关闭

image.png

image.png

8.ok将这些配置完成之后你就可以在企业微信侧边栏里面访问你的本地项目了

image.png

企业微信SDK的使用

既然是企业微信侧边栏，那么在实际的开放过程中肯定会使用到企业微信的相关SDK了

如：登录授权，发送小程序，获取微信用户头像信息等功能

一.首先引入企业微信SDK的相关链接
  <!--  需要调用JS接口的页面引入如下JS文件 z  -->
  <script src="https://res.wx.qq.com/open/js/jweixin-1.2.0.js" type="text/javascript"></script>
  <!--调用 wx.agentConfig需要引入 jwxwork sdk-->
  <script src="https://open.work.weixin.qq.com/wwopen/js/jwxwork-1.0.0.js"></script>
二.企业微信登录授权功能流程图

image.png

三.登录授权功能的实现

1.首先在进入页面时会先判断当前url是否有code参数

2.如果有code则走登录逻辑（企业微信侧边栏一般默认都是静默登录）,否则就跳转企业微信授权页面

3.相关代码参考vue3

<script setup>
import { onUnmounted, onMounted } from "vue";
onMounted(() => {
  const { options } = router;
  const query = options.history.location;
  const queryObj = getQueryParams(query);

  if (!queryObj.code) {
    onChangeAuth();
  } else {
    login(queryObj);
  }
});
// 调用登录接口
const login = async ({ code, redirect }) => {
   
};

// 手动授权
const onChangeAuth = async () => {
  window.sessionStorage.clear();
  const url = encodeURIComponent(window.location.href);
  let searchObj = null;
  searchObj = {
    appid: '', //当前企业的ID
    redirect_uri: url,
    response_type: "code",
    scope: "snsapi_privateinfo",
    agentid: 100001, // 企业应用ID
    state: "patient",
  };
 // 处理参数格式
  const search = Object.entries(searchObj)
    .map((entry) => {
      const [key, value] = entry;
      return `${key}=${value}`;
    })
    .join("&");
    //构建跳转授权页面链接
  window.location.href = `https://open.weixin.qq.com/connect/oauth2/authorize?${search}#wechat_redirect`;
};

// 解析url中的参数
const getQueryParams = (url) => {
  const paramArr = url.slice(url.indexOf("?") + 1).split("&");
  const params = {};
  paramArr.map((param) => {
    const [key, val] = param.split("=");
    params[key] = decodeURIComponent(val);
  });
  return params;
};
</script>

效果图： image.png

如何调用企业微信API?

1.首先在需要调用JS接口的页面引入如下JS文件

 <script src="https://res.wx.qq.com/open/js/jweixin-1.2.0.js" type="text/javascript"></script>

2.通过config接口注入权限验证配置

注意：所有需要使用JS-SDK的页面必须先注入配置信息，否则将无法调用（同一个url仅需调用一次，对于变化url的SPA（single-page application）的web app可在每次url变化时进行调用）

wx.config({
    beta: true,// 必须这么写，否则wx.invoke调用形式的jsapi会有问题
    debug: true, // 开启调试模式,调用的所有api的返回值会在客户端alert出来，若要查看传入的参数，可以在pc端打开，参数信息会通过log打出，仅在pc端时才会打印。
    appId: '', // 必填，企业微信的corpID，必须是本企业的corpID，不允许跨企业使用
    timestamp: '', // 必填，生成签名的时间戳 这个一般是后端生成的
    nonceStr: '', // 必填，生成签名的随机串 这个一般是后端生成的
    signature: '',// 必填，签名  这个一般是后端生成的
    jsApiList: ['sendChatMessage','getCurExternalContact'] // 必填，需要使用的JS接口列表，凡是要调用的接口都需要传进来
});

3.通过ready接口处理成功验证

wx.ready(function(){ 
// config信息验证后会执行ready方法，所有接口调用都必须在config接口获得结果之后，config是一个客户端的异
//步操作，所以如果需要在页面加载时就调用相关接口，则须把相关接口放在ready函数中调用来确保正确执行。对于
//用户触发时才调用的接口，则可以直接调用，不需要放在ready函数中。
});

4.通过error接口处理失败验证

wx.error(function(res){ // config信息验证失败会执行error函数，如签名过期导致验证失败，具体错误信息可以打开config的debug模式查看，也可以在返回的res参数中查看，对于SPA可以在这里更新签名。 });

5.通过agentConfig注入应用的权限,注：必须在wx.config ready成功之后才可以调用

	// 初始化成功
		wx.ready(async () => {
			console.log('wx-sdk初始化成功')
			// 初始化需要使用的SDK方法
			const params = { url: paramUrl, corpId, agentId, isAgent: true, orgID };
			const { success, data } = await getQwSign(params)
			if (success) {
				wx.agentConfig({
					corpid: '',// 必填，企业微信的corpid，必须与当前登录的企业一致
					agentid: '', // 必填，企业微信的应用id （e.g. 1000247）
					timestamp: , // 必填，生成签名的时间戳 这个一般是后端生成的
					nonceStr: '', // 必填，生成签名的随机串 这个一般是后端生成的
					signature: '',// 必填，权限签名算法 这个一般是后端生成的
					jsApiList: ['selectExternalContact'], //必填，传入需要使用的接口名称
					success: async () => {
						console.log('wx-sdk授权成功')
					
					},
					fail: function (res) {
						showToast({ message: res.errMsg })
						if (res.errMsg.indexOf("function not exist") > -1) {
							alert("版本过低请升级");
						}
					},
				});
			}
		});

注：agentConfig的作用
config注入的是企业的身份与权限，而agentConfig注入的是应用的身份与权限。尤其是当调用者为第三方服务商时，通过config无法准确区分出调用者是哪个第三方应用，而在部分场景下，又必须严谨区分出第三方应用的身份，此时即需要通过agentConfig来注入应用的身份信息。

6.调用sdk

在 wx.config ，wx.ready 和 wx.agentConfig 都调用成功之后就表示企业微信SDK方法注入成功

你就可以在页面去使用了，如：推送小程序功能

  wx.invoke(
    "sendChatMessage",
    {
      msgtype: "miniprogram", //消息类型，必填
      enterChat: true, //为true时表示发送完成之后顺便进入会话，仅移动端3.1.10及以上版本支持该字段
      miniprogram: {
        appid: '', //小程序的appid，企业已关联的任一个小程序
        title: '', //小程序消息的title
        imgUrl:"", //小程序消息的封面图。必须带http或者https协议头，否则报错 $apiName$:fail invalid imgUrl     
        page: "/pages/home/home.html", //小程序消息打开后的路径，注意要以.html作为后缀，否则在微信端打开会提示找不到页面
      },
    },
    function (res) {
      console.log("wx.invoke('sendChatMessage') =>", res);
      if (res.err_msg == "sendChatMessage:ok") {
        //发送成功
        showToast({ message: "操作成功" });
      }
    }
  );

sendChatMessage:ok 表示调用成功

image.png

相关参考链接

1.企业微信开发者中心：developer.work.weixin.qq.com/document/pa…

2.whistle wproxy.org/whistle/ins…

wproxy.org/whistle/web…

3.企业微信侧边栏教程：wecom-sidebar.github.io/wecom-sideb…

avatar
文章
阅读
粉丝