第三方应用开发
小程序
基础
连接微信
办公
JS-SDK
基础
连接微信
办公
第三方应用开发
客户端API
JS-SDK
开发指南
开始使用
开始使用
最后更新:2024/11/28

目录

  • 安装
  • 接口鉴权
  •       调用要求
  •       企业身份注册
  •       应用身份注册
  • 接口约定
  • 开发环境快速接入
  • 旧版jweixin迁移
  •       迁移指南
  • 安装

    企业微信JS-SDK提供了 npm 和 cdn 两种引入途径。

    1. 通过 npm 引入
      npm install @wecom/jssdk

      安装完成后即可在应用中使用 SDK:
      import * as ww from '@wecom/jssdk'
    2. 通过 script 标签引入
      <script src="https://wwcdn.weixin.qq.com/node/open/js/wecom-jssdk-2.0.2.js"></script>

      安装完成后,SDK 会在 window 上定义 ww 对象:
      <script>
        alert(ww.SDK_VERSION)
      </script>

    接口鉴权

    调用要求

    • 所有的JS接口只能在企业微信应用的可信域名下调用(包括子域名),且可信域名必须有ICP备案且在管理端验证域名归属。
    • 验证域名归属的方法在企业微信的管理后台“我的应用”里,进入应用,设置应用可信域名。
    • 在调用 JSAPI 前,需要先通过 ww.register 注册当前页面的身份信息。身份信息分为两种:
      1) 企业身份与权限,通过企业签名获得。
      2) 应用(自建/待开发/第三方应用等)身份与权限,通过应用签名获得。
      使用者可根据具体调用的JSAPI所要求的身份权限进行注册即可,应用身份权限 > 企业身份权限。

    企业身份注册

    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 签名算法

    注意:

    • 参数中的回调函数调用时机由 JSSDK 自行控制,开发者无需关心具体调用顺序
    • 用于生成签名的 jsapi_ticket 属于敏感信息,请在服务端完成签名操作

    应用身份注册

    应用在原有企业身份信息的基础上,需要额外提供应用身份信息(原 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

    旧版jweixin迁移

    新版的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对象)来调用,参数是一个对象,除了每个接口本身需要传的参数之外,还有以下通用参数:

    1. success:接口调用成功时执行的回调函数。
    2. fail:接口调用失败时执行的回调函数。
    3. complete:接口调用完成时执行的回调函数,无论成功或失败都会执行。
    4. cancel:用户点击取消时的回调函数,仅部分有用户取消操作的api才会用到。
    5. trigger: 监听Menu中的按钮点击时触发的方法,该方法仅支持Menu中的相关接口。
    不要尝试在 trigger 中使用 Ajax 异步请求修改本次分享的内容,因为客户端分享操作是一个同步操作,这时候使用 Ajax 的回包会还没有返回。

    以上几个函数都带有一个参数,类型为对象,其中除了每个接口本身返回的数据之外,还有一个通用属性err_msg,其值格式如下:

    1. 调用成功时:"xxx:ok" ,其中xxx为调用的接口名
    2. 用户取消时:"xxx:cancel",其中xxx为调用的接口名
    3. 调用失败时:其值为具体错误信息
    上一篇概述
    下一篇 应用登录签名
      本节内容
    服务端API
    基础
    数据与智能专区
    应用接收专区通知
    连接微信
    客户联系
    办公
    小程序接入对外收款
    客户端API
    小程序
    基础
    连接微信
    办公
    JS-SDK
    基础
    连接微信
    办公
    更新日志
    联系我们