企业微信开发第三方H5应用开发踩坑

零.前言

因业务需要, 需要将我们的系统与企业微信进行对接, 特此记录一下其中的点

• 开发工具: 因为工具用的是企业微信, 不能设置 debugger, 否则企业微信卡死
• 企业微信的 debug 模式无法进行移动端适配

一.概念理清

官方的开发需知一定要认真读, 理清基本的概念:

1.企业内部应用和第三方应用

2.上线和上架

**一定要仔细读文档, 一定要仔细读文档, 一定要仔细读文档, **

二.快速开始

作为一个前端, 如何准备哪些东西, 方便快速开始自己的项目呢?

除了看官方文档的快速入门, 这里总结了下流程:

1.创建一个企业微信账户

你所在企业作为第三方应用服务商开发应用, 开发完成需要另外一个企业作为使用方使用你的应用, 为了方便测试, 最好的方法是,以你的账号申请一个企业, 用来安装应用进行测试

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-2IDTX7y1-1676479388491)(http://note.youdao.com/yws/public/resource/1f466420b40e359c829bda0a8716b54a/xmlnote/1171760127A641038EB53188B17C9AE2/59631)]

2.创建应用

需要你所在企业的企业管理员扫码登录企业微信服务商后台, 在应用管理那里选择-> 创建项目, 之后在应用主页设置各种配置信息

3.可信域名与内网穿透

由于企业微信(微信,微信公众号,小程序 webview 可信域名授权同理)的第三方 H5 应用需要配置可信域名, 而本地开发地址显然是无法通过企业微信的域名校验的，解决的方法目前有两种：

方法一. 修改本地的 host 和使用 nginx 代理(推荐)

假设本地跑了一个服务，访问地址为: localhost:8080

1. host 文件修改

sudo vi /etc/hosts

不会 vi 可以使用熟悉的编辑器, 如 vscode 打开(需要执行 ctrl+shift +p => install code command in Path)

sudo code /etc/hosts

编辑文件,添加下面一行并保存

127.0.0.1 www.example.com(自行替换)

尝试访问: http://www.example.com:8080，(注意不是 https), 应该能看到页面了,

如果不成，ping 一下

ping www.example.com

64 bytes from 127.0.0.1: icmp_seq=0 ttl=64 time=0.051 ms
64 bytes from 127.0.0.1: icmp_seq=1 ttl=64 time=0.158 ms

2. nginx 代理

但是我们在填写主页地址的时候是只能填写不带端口的地址的，因此需要使用 nginx 来做反向代理，实现https://www.example.com的访问

nginx 安装

ssl 证书安装

ps1: 遇见无权限的时候执行

chmod +x ./gencert.sh

ps2: 按照作者的流程搞完之后，多了以下几个文件

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-rbltaQv8-1676479388492)(http://note.youdao.com/yws/public/resource/1f466420b40e359c829bda0a8716b54a/xmlnote/031896BFEAC04A3AB292227F03A0CAE3/59611)]

nginx.conf 文件, 位于/usr/local/nginx/conf, /etc/nginx, 或 /usr/local/etc/nginx. 可直接用

可以使用下列命令查看 conf 文件位置

nginx -t

worker_processes  1;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;
    # HTTPS server
    server {
       listen       443 ssl;
       server_name  www.example.com;

       ssl_certificate      /usr/local/etc/nginx/ssl/www.example.com.crt;
       ssl_certificate_key  /usr/local/etc/nginx/ssl/www.example.com.key;

       ssl_session_cache    shared:SSL:1m;
       ssl_session_timeout  5m;

       ssl_ciphers  HIGH:!aNULL:!MD5;
       ssl_prefer_server_ciphers  on;

       location / {
           root   html;
           index  index.html index.htm;
           proxy_pass          http://localhost:8080;
       }
    }
    include servers/*;
}

方法二. 使用花生壳等内网穿透工具(后期比较麻烦，不推荐)

原理感兴趣可以自行搜索,简单而言就是可以把你的本地localhost的服务映射到公网的地址, 以花生壳为例,会自动分配一个域名给你, xxxxxxx.oicp.vip, 配置好穿透之后, 将对应的域名填上去就好了.

不推荐的原因:

1. 域名需要实名验证，而且每过两天就会让你验证一次，比较麻烦
2. 付费，而且有流量限制
3. 花生壳的这种域名在微信是打不开的，所以如果你用了家校通的话，家长从微信打开会有问题

三.设置各种回调

这步需要后端人员的配合, 只有这步走完之后才能够进行测试

四.本地开发与安装调试

1.安装

当前端项目初始化完成, 后端回调配置 ok 之后, 就可以尝试安装了, 具体看文档

安装完成之后使用你的测试企业, 进入应用管理, 点开相关的应用, 进行配置, 比如可见范围设置所有开发人员可见

2.调试

方法一：
打开微信开发者工具，选择公众号模式, 但是不一定成功

方法二：

企业微信内部可以启用开发者模式

• mac: ctrl + command + shift + D

然后右键点击-> 审查元素即可

但是有几点坑的地方:

1. 别加 debugger, 会直接卡死
2. 无法使用移动端模拟器, 如 iphone6

ps: 微信小程序开发工具目前已经有企业微信小程序的支持

五.接入授权

因为我们是 H5 应用, 需要走网页授权拿到用户的身份信息, 参考网页授权登录

授权需要放置校验文件，项目使用的是 uniapp, 在 public 文件夹放置校验文件, 只要你能够通过www.test.com/MEkcNmXU1TXwd0eZ.txt访问到该文件就行, 线上部署,每次 build 项目的时候, 也需要添加相应的校验文件

"build": "npm run build:h5 && npm run verify",
"verify": "echo 'MEkcNmXU1TXwd0eZ' > dist/build/h5/WW_verify_MEkcNmXU1TXwd0eZ.txt",

六.接入 sdk

签名会比较麻烦, 主要是后端处理

引入 sdk

两个 sdk, 第一个用户普通接口,比如扫码, 需要 config 配置, 一个用于企业微信特定的 API, 比如获取企业微信联系人

引入之后是没有wx对象的, 只有jweixin对象

const wx = window.jWeixin

使用模块引入

63002 错误码

1. 确认 timestamp 是 s, 也就是 10 位
2. 确认后端要对 url 进行 decode
3. agentConifg 签名用的 noncestr 和 timestamp 必须与 wx.config 中的 nonceStr 和 timestamp 相同。

七.总结

走完上面几步, 基本的开发步骤就算走完了, 接下来是真正的需求实现, 期间也遇到不少坑, 想到再补吧

八.踩坑汇总

1. 多平台接入

因为我们的 H5 应用此前对接了很多平台，而作为企业微信第三方 H5 应用使用的，接入的是企业微信的家校通，所以就要考虑以下情况

• 普通 H5 登录, 走普通登录页面
• 家长从微信打开普通的 H5, 需要走的微信的授权
• (企业微信通讯录同步的)家长从微信打开家校通入口，找到我的学校，在我的学校里面打开 H5, 需要走的是企业微信的授权
• 企业微信的推送通知, 需要走的是企业微信授权
• (企业微信通讯录同步的)老师从企业微信打开，需要走的是企业微信的授权

问题来了: 无法通过判断 userAgent 的形式判断是需要走微信的授权,还是企业微信授权, 因此需要传递某些特定的参数, 如system=work-wechat

if (
  String(navigator.userAgent.toLowerCase().match(/MicroMessenger/i)) ===
    "micromessenger" &&
  system !== "work-wechat"
) {
  uni.setStorageSync("platform", "wechat"); // 微信平台
}

2. 企业微信 40029 状态码报错: 不合法的 oauth_code

原因一: 微信出现两次重定向, 而两次携带的都是相同的 code, 第一次使用之后 code 就失效了
解决: 添加connect_redirect=1字段到链接中

const redirectUrl = `https://open.weixin.qq.com/connect/oauth2/authorize?appid=wwa8575b53d140807a&redirect_uri=${process.env.VUE_APP_WORKWECHAT_REDIRECT_ENDPOINT}%2Fpages%2Flogin%2Fwork-wechat&response_type=code&scope=snsapi_userinfo&state=normal&connect_redirect=1#wechat_redirect`;

window.location.href = redirectUrl;

原因二: 构造链接中的 appid 没有填写正确

检查构造的 redirectUrl 中的 appid 和 secret 是否填写正确，由于我们的应用有两个，为教师端和家长端，测的时候匆忙，错把家长端的 appid 当成了学校端的