企业微信自建应用的常见问题及解决方法
最近公司要做企业微信自建应用,坑!!!实在是坑!!!,文档描述的不具体,导致走了很多弯路,百度查了一大堆,论坛一大堆,参考资料真的是少之又少,没有一个成型的Demo,踩了很多坑,从上搞到下,搞的呕心沥血,最后还是自己搞。
下面,讲下我开发时候一些心得和流程,保你万无一失。
搭建自建应用
-
登录企业微信后台
应用管理 -> 应用 -> 自建 -> 创建应用
-
点击创建好的应用进入应用配置页面
构建自建应用网页授权
官方文档:work.weixin.qq.com/api/doc/900…
企业微信OAuth2接入流程如图
设置可信域名
应用配置页面:应用管理->应用->自建->点击已创建的应用,进入应用配置页面
注意:
- 可信域名配置的是前端页面的域名,不是后端请求的域名
- 如果非80端口,必须可信域名配置必须包含端口号
- 配置域名与访问域名完全一致,与协议头/链接路径无关
参考官网实例
假定重定向访问的链接是:mail.qq.com:8080/cgi-bin/hel…
配置域名 | 是否正确 | 原因 |
---|---|---|
mail.qq.com:8080 | ✅ | 配置域名与访问域名完全一致 |
email.qq.com | ❌ | 配置域名必须与访问域名完全一致 |
support.mail.qq.com | ❌ | 配置域名必须与访问域名完全一致 |
*.qq.com | ❌ | 不支持泛域名设置 |
mail.qq.com | ❌ | 配置域名必须与访问域名完全一致,包括端口号 |
假定配置的可信域名是 mail.qq.com:
访问链接 | 是否正确 | 原因 |
---|---|---|
mail.qq.com/cgi-bin/hel… | ✅ | 配置域名与访问域名完全一致 |
mail.qq.com/cgi-bin/red… | ✅ | 配置域名与访问域名完全一致,与协议头/链接路径无关 |
exmail.qq.com/cgi-bin/hel… | ❌ | 配置域名必须与访问域名完全一致 |
配置首页链接
- 配置应用首页链接入口地址
-
构造应用首页链接
应用链接固定格式如下,具体链接参数说明见官方文档 work.weixin.qq.com/api/doc/900…
https://open.weixin.qq.com/connect/oauth2/authorize?appid=CORPID&redirect_uri=REDIRECT_URI&response_type=code&scope=snsapi_base&state=STATE#wechat_redirect
我们需要配置两个参数,其他参数默认
-
appid,就是企业ID
企业微信后台 -> 我的企业 -> 企业信息 底部有企业Id
-
redirect_uri 实际的首页链接
授权后重定向的回调链接地址,请使用urlencode对链接进行处理
-
-
如何测试构造的链接
浏览器端访问
此链接不可在浏览器端访问,会提示在微信客户端打开
微信开发者工具访问
我们使用微信开发者工具打开,选择公众号网页打开
在链接输入框中输入测试连接,提示未绑定企业号开发者
如何绑定企业号开发者
我的企业 -> 微信插件 -> 开发者工具勾选上
配置完整之后就可以正常访问链接进行测试了
获取用户信息
这步操作基本是后台封装接口直接调用,可以仔细阅读参考文档,这里不多说都有想起返回结果
根据code获取成员信息:work.weixin.qq.com/api/doc/900…
根据userid读取成员:work.weixin.qq.com/api/doc/900…
到这步基本没啥遇到什么深坑,正常处理!!
JS-SDK 实践
以聊天栏增加功能为例说明JS-SDK的使用,使用JS-SDK获取外部联系人
设置聊天栏功能
位置一:
企业微信管理后台,应用管理 -> 应用 -> 自建,点击创建好的应用,进入应用详情查看
具体链接配置和上文中的授权链接配置一样,配置完成后,登录企业微信之后和客户聊天窗口中就可以看见聊天栏中配置的功能
位置二:
企业微信管理后台,客户 -> 配置 -> 聊天工具栏管理
JS-SDK权限验证
步骤一: 引入js-sdk相关js
<script src="//res.wx.qq.com/open/js/jweixin-1.2.0.js "></script>
步骤二: 通过wx.config注入权限验证配置(第一次握手config注入的是企业的身份与权限)
wx.config({
beta: true,// 必须这么写,否则wx.invoke调用形式的jsapi会有问题
debug: true, // 开启调试模式,调用的所有api的返回值会在客户端alert出来,若要查看传入的参数,可以在pc端打开,参数信息会通过log打出,仅在pc端时才会打印。
appId: '', // 必填,企业微信的corpID
timestamp: , // 必填,生成签名的时间戳
nonceStr: '', // 必填,生成签名的随机串
signature: '',// 必填,签名,见 附录-JS-SDK使用权限签名算法
jsApiList: [] // 必填,需要使用的JS接口列表,凡是要调用的接口都需要传进来
});
这里需要主要点
- appId 对应的是企业微信的corpID
- timestamp,nonceStr,signature签名生成一般让后端是返回给前端
调用后端请求,生成timestamp,nonceStr,signature如下
// 这里是一个后端请求,只需要注意参数就可以
await this.props.getWxconfig({
appSecret: "-",
appid: '-',
locationUrl: url
})
参数说明
- appid:企业微信的corpID
- appSecret:外部联系人secret
- locationUrl:授权访问的页面URL
外部联系人secret如何查看
步骤三: 通过wx.ready接口处理成功验证(第二次握手判断当前版本是否支持指定 JS 接口,支持批量判断)
步骤四: 通过agentConfig注入应用权限(第三次握手gentConfig注入的是应用的身份与权限)
wx.ready(function() {
// config信息验证后会执行ready方法,所有接口调用都必须在config接口获得结果之后,config是一个客户端的异步操作,
// 所以如果需要在页面加载时就调用相关接口,
// 则须把相关接口放在ready函数中调用来确保正确执行。对于用户触发时才调用的接口,则可以直接调用,不需要放在ready函数中。
wx.checkJsApi({
jsApiList: ['agentConfig', 'getCurExternalContact'], // 需要检测的JS接口列表,所有JS接口列表见附录2,
success: (res) => {
// 以键值对的形式返回,可用的api值true,不可用为false
// 如:{"checkResult":{"chooseImage":true},"errMsg":"checkJsApi:ok"}
wx.agentConfig({
corpid: '', // 必填,企业微信的corpid,必须与当前登录的企业一致
agentid: '1000004', // 必填,企业微信的应用id (e.g. 1000247)
timestamp: wxConfig.agent_timestamp,
nonceStr: wxConfig.agent_nonceStr,
signature: wxConfig.agent_signature,
jsApiList: ['getCurExternalContact'], //必填
success: (res) => {
// 回调
wx.invoke('getCurExternalContact', {
}, function(res){
if(res.err_msg == "getCurExternalContact:ok"){
userId = res.userId ; //返回当前外部联系人userId
}else {
//错误处理
}
});
},
fail: (res) => {
if (res.errMsg.indexOf('function not exist') > -1) {
alert('版本过低请升级')
}
},
complete: (res) => {}
})
}
})
});
调用agentConfig的注意事项
- agentConfig与config的签名算法完全一样,但是jsapi_ticket的获取方法不一样(后端注意)
- 调用wx.agentConfig之前,必须确保先成功调用wx.config
- 当前页面url中的域名必须是在该应用中设置的可信域名。
- agentConfig仅在企业微信2.5.0及以后版本支持,微信客户端不支持(微信开发者工具也不支持)
- agentConfig的接口列表有getCurExternalContact
==小编友情提醒==:开发时候我们肯定会有多套应用环境的部署(测试,生产),所以我们需要在企业后台进行多个应用的创建,然后一些可变动的参数尽量动态获取 列如,执行agentConfig(AgentId这个是根据应用走的参数),到此我们要进行前面的步骤完成一个应用,这里隐藏了一个不为认知的坑,就是多个环境调试时候,会一直遇到 getCurExternalContact:fail_nopermission,那么问题来了,步骤都对了,agenConfig也是ok,就是获取外部联系人方法 不可用,这里就去找到客户联系配置外部联系人关联的应用,如图
到这里就就可以进行正常的多套环境应用调试。
常见问题总结
-
invalid signature
这个问题基本要通过https://work.weixin.qq.com/api/jsapisign,签名工具是排查看下后台返回的和工具生成的是否一样,前后端配合下
-
fail_nopermission
这个坑了我很久,从文档看就是 config 没执行, JSAPI没有传入config的jsApiList参数中,。
-
no permission
wx.agentConfig 没有调用成功,一般是签名错误,它和config 签名是不一样的,如问题1 invalid signature
-
wx.xxx is not a function
说明你页面引入的那个js 不对全局在检查下。
-
因为有的微信开发者工具不支持企业微信的一些方法,所以测试的时候只能在手机端企业微信进行。推荐大家使用调试插件VCONSE
推荐阅读
-
基于springboot开发的企业微信第三方应用(V)(实现登录并获取用户信息)
-
企业微信开发第三方应用的扫码授权登录
-
如何在Genymotion中启用微信、QQ及陌陌等应用的支持
-
玩转微信群里的Python机器人!如何在手机和电脑上添加?" * 手机端:进入企业微信内部群聊,点击右上角的群组,找到并添加群机器人按钮。 * 电脑端:选中群聊后,右键点击鼠标以添加机器人按钮。 * 群机器*限管理:为了方便管理,管理员可在企业微信管理后台的应用管理内,限制只有白名单内的员工才能开启群机器人的权限。 * 外部群群机器人添加入口:如果你不是企业微信的管理员,你可以通过外部群群机器人的添加入口来添加。
-
遇到uniapp开发企业微信H5应用的wx或jWeixin问题?看这里,找到解决方案!
-
企业微信定制应用:保障企业安全的可信IP设置
-
如何让JEEWX企业号和微信企业号无缝对接?激活应用回调模式的详细步骤
-
企业微信 H5 应用在本地和真机上的调试:Host 配置与代理的指南
-
微信、企业微信和微信小程序开发中常见问题的全面总结
-
在Vue中实现对企业微信自建应用的授权方式:静默授权、手动授权与扫码授权