目录
企业微信JS-SDK提供了 npm 和 cdn 两种引入途径。
npm install @wecom/jssdk
import * as ww from '@wecom/jssdk'
<script src="https://wwcdn.weixin.qq.com/node/open/js/wecom-jssdk-2.0.2.js"></script>
<script>
alert(ww.SDK_VERSION)
</script>
ww.register({
corpId: 'ww7ca4776b2a70000', // 必填,当前用户企业所属企业ID
jsApiList: ['getExternalContact'], // 必填,需要使用的JSAPI列表
getConfigSignature // 必填,根据url生成企业签名的回调函数
})
async function getConfigSignature(url) {
// 根据 url 生成企业签名
// 生成方法参考 https://developer.work.weixin.qq.com/document/14924
return { timestamp, nonceStr, signature }
}
在注册应用身份信息时,开发者需要提供对应的签名函数。该函数需要根据当前页面的 URL 和应用的 Secret 等信息生成 JS-SDK 签名并返回相关信息。详见 JS-SDK 签名算法。
注意:
应用在原有企业身份信息的基础上,需要额外提供应用身份信息(原 agentConfig):
ww.register({
corpId: 'ww7ca4776b2a70000', // 必填,当前用户企业所属企业ID
agentId: 1000247, // 必填,当前应用的AgentID
jsApiList: ['getExternalContact'], // 必填,需要使用的JSAPI列表
getConfigSignature, // 必填,根据url生成企业签名的回调函数
getAgentConfigSignature // 必填,根据url生成应用签名的回调函数
})
async function getConfigSignature(url) {
// 根据 url 生成企业签名
// 生成方法参考 https://developer.work.weixin.qq.com/document/14924
return { timestamp, nonceStr, signature }
}
async function getAgentConfigSignature(url) {
// 根据 url 生成应用签名,生成方法同上,但需要使用应用的 jsapi_ticket
return { timestamp, nonceStr, signature }
}
应用在原有签名函数的基础上,需要额外提供应用的AgentID以及应用签名函数。和原有的签名函数不同,应用签名函数需要使用应用的 jsapi_ticket。见 获取应用 jsapi_ticket。
注意:用于生成签名的 jsapi_ticket 属于敏感信息,请在服务端完成签名操作。
在调用 ww.register 后,页面可以立刻调用其他 JSAPI,JS-SDK 内部会自行处理注册身份信息的时序。这里约定两种通用的 JS 接口调用形式:
1. 命令接口:
ww.方法名({
参数: xxx,
success(result) {
// 成功回调,result.errMsg 固定格式为“方法名:ok”
},
fail(result) {
// 失败回调,通过 result.errMsg 查看失败详情
},
complete(result) {
// 完成回调,无论调用成功还是失败,都会回调该方法
}
})
2. 事件接口:
ww.on事件名(event => {
// 事件发生时回调
})
另外所有命令接口均会返回 promise,开发者也可以通过 promise 的回调获取调用结果:
const { errMsg, userIds } = await ww.selectExternalContact()
// errMsg === 'selectExternalContact:ok'
为方便开发者在开发环境快速接入,JS-SDK 提供了 getSignature 方法,开发者可以通过内联 jsapi_ticket 在页面上生成 JSAPI 签名:
// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
// 该代码仅用于开发环境快速接入,请勿在生产环境对外暴露JSAPI_TICKET
// Ticket有效期为2个小时,过期后请手动更换
// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
const JSAPI_TICKET = 'sM4AOVdWfPE4DxkXGEs8VMCPGGVi4C3VM0P37wVUCFvkVAy_90u5h9nbSlYy3-Sl-HhTdfl2fzFy1AOcHKP7qg '
ww.register({
corpId: 'ww7ca4776b2a70000',
jsApiList: ['selectExternalContact'],
getConfigSignature() {
return ww.getSignature(JSAPI_TICKET)
}
})
// 调用 register 后可以立刻调用其他 JS 接口
ww.selectExternalContact({
success(res) {
alert(JSON.stringify(res))
}
})
jsapi_ticket 的获取方法可以参考获取企业 jsapi_ticket和获取应用 jsapi_ticket,在开发阶段我们也可以通过以下命令快速获取:
# CORPID、SECRET为占位符,请自行填入真实的企业ID和应用Secret
npx wwutil ticket CORPID SECRET
新版的wecom-jssdk.js中,我们提供了完全的Typescript类型支持,npm引入等新特性。未来企业微信中新功能接口也将基于wecom-jssdk进行更新升级。如果你的应用正在使用旧版 jweixin-1.2.0.js进行接口调用,我们强烈建议进行升级。
非兼容性的改变:
1、wx.config, wx.agentConfig 需改为使用ww.register进行身份注册。
2、ww.register方法,开发者无需关注ready等注册状态,SDK内部会自动处理相关函数回调。
兼容性改变:
ww.invoke方法,ww.on方法 均兼容旧版的wx.invoke,wx.on方法,可以直接进行替换。
以下为旧版 jweixin-1.2.0.js 的接入和使用方式。
步骤一:引入JS文件
在需要调用JS接口的页面引入如下JS文件:https://res.wx.qq.com/open/js/jweixin-1.2.0.js
<script src="https://res.wx.qq.com/open/js/jweixin-1.2.0.js"></script>
为支持微信插件(原企业号)功能,请引用此文件。原企业微信的js文件在微信插件不生效。
jweixin-1.6.0 版本企业微信客户端暂不支持。
步骤二:通过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: '',// 必填,签名,见 附录-JS-SDK使用权限签名算法
jsApiList: [] // 必填,需要使用的JS接口列表,凡是要调用的接口都需要传进来
});
生成签名算法详见:附录-JS-SDK使用权限签名算法
步骤三:通过ready接口处理成功验证
wx.ready(function(){
// config信息验证后会执行ready方法,所有接口调用都必须在config接口获得结果之后,config是一个客户端的异步操作,所以如果需要在页面加载时就调用相关接口,则须把相关接口放在ready函数中调用来确保正确执行。对于用户触发时才调用的接口,则可以直接调用,不需要放在ready函数中。
});
步骤四:通过error接口处理失败验证
wx.error(function(res){
// config信息验证失败会执行error函数,如签名过期导致验证失败,具体错误信息可以打开config的debug模式查看,也可以在返回的res参数中查看,对于SPA可以在这里更新签名。
});
接口调用说明
所有接口通过wx对象(也可使用jWeixin对象)来调用,参数是一个对象,除了每个接口本身需要传的参数之外,还有以下通用参数:
不要尝试在 trigger 中使用 Ajax 异步请求修改本次分享的内容,因为客户端分享操作是一个同步操作,这时候使用 Ajax 的回包会还没有返回。
以上几个函数都带有一个参数,类型为对象,其中除了每个接口本身返回的数据之外,还有一个通用属性err_msg,其值格式如下: