反馈已提交

网络繁忙

微信集成

  • 文档创建者:susie
  • 历史版本:139
  • 最近更新:April陶 于 2024-02-23
  • 1. 概述

    1.1 版本

    使用企业微信,需要报表服务器、H5、微信插件版本均匹配才能集成,版本的对应情况如下表所示:

    报表服务器版本

    微信管理插件版本

    功能变动
    11.0.2V11.0.54微信管理支持将企业微信用户同步到「用户管理」,参考本文第 4.3.3 节
    11.0.3
    V11.0.62
    • 「应用快捷配置>生成微信链接」支持,生成自定义链接,详情参见本文 4.2.3 

    • 「成员管理」支持同步多个企业的数据

    11.0.9
    V11.0.74优化单点登录性能

    1.2 功能简介

    • 安装微信管理插件,可实现微信集成

    • 在定时调度的输出设置中,可以配置并推送微信消息

    • 支持集成多个应用

    1.3 注意事项

    注意事项 1 

    报表服务器一定是可以被外网访问的,并且一定是域名地址,不能用 IP 地址。

    域名地址举例http://xxx.xxx.com:xxx/webroot/decision。

    如果是http://IP:xxx/webroot/decision,是不可以做微信集成的。

    注意事项 2 

    报表服务器需要能访问微信服务器。

    若报表服务器在内网,无法访问到微信服务器的话,支持正向代理配置,代理配置参考:微信钉钉集成环境准备第 4 节

    注意事项 3 

    微信集成下若使用「扫码控件」、「文件控件」, 则要求单点登录、且域名必须经过校验。

    校验方法请参考:「微信集成」文件控件&文本控件扫码无法使用

    2. 环境准备

    2.1 安装插件

    点击下载插件:微信管理HTML5 移动端展现插件

    设计器插件安装方法请参见:设计器插件管理

    服务器安装插件方法请参见:服务器插件管理

    注:微信/钉钉集成过程中,必须确保各版本相对应,详情参见:微信、钉钉、H5、服务器、JAR 之间的依赖关系

    2.2 配置网络环境

    在微信集成之前,必须先完成网络环境配置,参考文档:微信钉钉集成环境准备

    3. 新建应用

    3.1 微信后台创建应用

    1)管理员登录企业微信后,在「应用管理」Tab 下点击「创建应用」,如下图所示:

    7.png

    2)上传应用 logo,填写「应用名称」,「应用介绍」选填,设置「可见范围」,设置完成后,点击「创建应用」,如下图所示:

    8.png

    若「可见范围」不是部门而是单独的微信用户,那么在平台「微信管理」的「成员管理」 Tab下会看不到用户信息,因为右边的组织机构是空的,而用户是属于部门的,所以也是空的。对于单独的微信用户,建议先在企业微信通讯录设置好标签,再通过标签的方式添加到FineReport中。

    3.2 配置可信IP和域名

    由于企业微信针对自建及代开发应用进行安全性升级,2022 年 6 月 20 日之后创建的新应用,都必须先配置可信IP和可信域名。



    登录企业微信后台,选择「应用管理」,选择对应的应用,设置「企业可信IP」。如果客户遇到添加IP,提示是第三方服务商IP(实际不是),需要找企业微信客服验证一下企业可信IP,如下图所示:

    详情参见:关于企业微信自建应用安全性升级的说明 。


    1682216466mdDO.png


    3.3 获取微信应用参数

    微信应用创建成功之后,需要关注两个参数:

      参数 含义 
      CorpID  企业 ID
      Secret   授权码

    3.3.1 CorpID

    点击「我的企业」,可查看「企业ID」,如下图所示:

    9.png

    注:企业 logo 和简称可以修改。

    3.3.2 Secret 

    1)点击「应用管理」,点击已创建的应用,如下图所示:

    7.png

    2)可查看 Secret ,如下图所示:

    10.png

    4. 平台微信管理

    以管理员身份进入数据决策系统,点击「管理系统」>「微信管理」,如下图所示:

    33.png

    4.1 应用管理

    4.1.1 报表服务器地址

    必须设置「报表服务器地址」并保存,如果不设置,推送的时候可能会有问题,报表服务器地址示例:

    http://域名:端口号/webroot/decision

    注:请使用二级或二级以上域名,且需通过 ICP 备案。

    输入「报表服务器地址」,如下图所示:

    13.png

    4.1.2 新建微信应用

    点击「新建微信应用」,输入相应的企业应用名称CorpIDSecret,点击「确定」,如下图所示:

    14.png注:请填写合乎规范的信息,企业应用名称、CorpID、Secret 不可为空,且应用名称不可与其他应用的重复。

    新建微信应用成功后,可对信息进行修改和删除,支持集成多个微信应用。如下图所示:

    15.png

    4.2 应用快捷配置

    4.2.1 微信代理跳转

    注1:若报表服务器配置在外网环境中,则不需要设置代理服务器地址。

    若服务器是配置在内网,访问不到微信服务器,访问不到外网的时候需要配置「代理服务器地址」。

    若服务器是配置在内网,且客户服务器和外网能互相访问到,网络正常,则「微信管理>应用快捷配置>代理服务器地址」,不需要填写。

    1)先判断报表服务器上,ping qyapi.weixin.qq.com,能 ping 通,代理服务器配置这边不用填写。
    2)ping不通,找一个代理服务器配置nginx正向代理,代理配置如下:

    server {
        listen 8113;  // 微信代理服务器端口
        server_name 10.2.2.3;  //微信代理服务器IP
        location / {
            proxy_redirect off;
            proxy_pass https://qyapi.weixin.qq.com;//微信服务器域名
        }
        location = /favicon.ico {
            log_not_found off;
        }
    }

    3)平台配置如下图所示:

    image.png

    文本框中输入正确的「代理服务器地址」,点击「测试连接」,提示「连接成功」并「保存」。

    如需要详细了解工程的网络环境要求,网络检测方法,以及对应的不同情况下的代理配置,请参考:微信钉钉集成环境准备第 4.2 节

    4.2.2 主页型应用快速配置

    功能简介:

    该功能即对微信主页应用进行快速配置,配置的内容包括:可信域名、应用主页链接、自定义菜单中设置一个菜单并添加主页链接。

    应用场景:

    如果客户这里要用配置的主页,是想要直接登录到平台,显示移动端的目录的话,只需要在上面点击微信「一键配置」,会自动把各个 url 都填写上的,不需要用户额外操作。

    操作步骤:

    默认为企业微信列表中的第一个,通过下拉框选择需要配置的企业应用名称,然后点击「一键配置」即可快速的配置主页型应用,不需要用户再到微信后台配置。如下图所示:

    17.png

    若配置前,微信应用的主页链接和菜单为空,点击「一键配置」按钮后,直接进行快速配置。进入微信应用,可信域名应用主页链接自定义菜单中设置一个菜单并添加主页链接已设置完成,如下图所示:

    1640331987993469.png

    4.2.3 生成微信链接

    • 生成链接的时候一定要选择对应企业应用名称。

    • 可以生成两种微信链接:一是用来单点登录到平台目录的;二是用来单点登录到模板的。

    注:使用 V11.0.74 插件生成的单点链接,若回退插件,需使用老版本插件重新生成链接配置主页。

    • 应用场景:应用的 主页 配置;

      定时调度最后一步「文件处理>客户端通知」推送「自定义链接」。可参考文档:定时调度任务详细设置步骤

      模板消息事件插件推送。 模板消息事件插件 可以将该链接推送给移动端用户,用户点开后即可访问链接对应的内容。


    4.2.3.1 生成微信链接

    1)生成访问决策平台的微信链接

    首先要选择企业应用名称,链接页面下拉选择决策平台,点击生成链接后,点击复制按钮即可,如下图所示:

    1604043327275823.png

    2)生成访问某个模板的微信链接

    首先要选择「企业应用名称」,链接页面下拉选择「单个模板」,然后选择一张模板,如果需要设置参数,可以点击「设置参数默认值」进行设置,设置了参数后点击「解析参数值」,最后点击「生成链接」,点击「复制」按钮即可,如下图所示:

    1604043736311077.png

    3)生成自定义链接

    生成在微信能够访问的轻应用链接。

    首先,选择「企业应用名称」,生成「自定义链接」并填入「移动端轻应用」中生成的链接。然后点击「生成链接」并复制即可。如下图所示:

    2023-12-27_11-03-27.png

    生成的链接:

    2023-12-27_11-07-44.png

    4.2.3.1 生成应用主页链接

    如果只想主页那边挂一个模板,且支持单点登录打开模板,不仅需要在这里生成对应模板链接。

    还需将生成的链接粘贴到微信工作台或者自定义菜单里。在「网页授权及JS-SDK」下设置可信域名/申请域名校验(域名例如:demo.fanruan.com,步骤请参考:「微信集成」文件控件&文本控件扫码无法使用)。

    注:设置可信域名就是说的你的微应用地址是可用的、合法的。


    a)设置「应用主页」。在「工作台应用主页」中点击设置「网页地址」,粘贴平台中生成的微信链接,点击「确定」。

    2022-01-21_16-59-00.png


    b)在「自定义菜单」中点击「设置」,填写主菜单,设置菜单内容为跳转到网页,填写网址(上面生成的微信链接粘贴过来),点击「保存」并「发布」。

    1640333917661089.png


    5)在「网页授权及JS-SDK」中点击设置可信域名,输入可信域名,点击确定。

    注:设置可信域名就是说的你的微应用地址是可用的、合法的。

    1617158783240361.png

    下面介绍下如何配置参数,如果想要使用「设置参数默认值」功能需要将插件更新到 V10.4.76 版本,如果想要使用「解析参数值」功能需要更新到 V10.4.97 版本。

    • 设置参数默认值

    点击「设置参数默认值」后,如果模板本身有参数,那么会显示在下方,用户可以设置参数的默认值,当然也可以点击右上角新增参数,如下图所示:

    注:如果想删除参数,可以鼠标悬浮在参数列表的右边,会出现删除按钮。

    1604045042139214.png

    • 解析参数值

    假如一张模板「a.cpt」设置了一个参数「date」,其值为公式${today}

    1. 如果勾选了「解析参数值」,那么点击「生成链接」后,链接中会自动解析出今天的日期,也就是变成了:a.cpt&date=2020-11-03。点开模板会自动显示今天的数据信息(2020-11-03)。

    2. 如果不想链接中直接解析参数,想要保留这个公式,可以取消勾选「解析参数值」,点击「生成链接」后,公式保留:a.cpt&date=${today}

    1604045214769389.png

    注1:微信/钉钉集成链接必须勾选解析参数值,否则将导致参数丢失。

    注2:模板消息推送的消息链接可选择不解析参数值,从而实现推送的公式计算。


    4.2.4 申请域名校验

    步骤请参考文档:「微信集成」文件控件&文本控件扫码无法使用

    4.2.5 新建微信群

    JAR 包在 2020-07-08 及之后,且企业微信管理插件在 V10.4.80 及之后的版本,新增微信群设置。

    用户可使用应用新建微信群,自定义微信群名称、群主和群成员,支持通过定时调度推送群消息到微信群。

    详情请参见:微信定时推送消息

    image.png

    4.3 成员管理

    4.3.1 用户匹配方式

    可根据实际情况选择一种用户匹配方式。

    用户匹配方式:微信号匹配手机账号匹配手动匹配自定义匹配。「成员管理」页面如下图所示:

    注1:不管集成几个微信应用,用户统一进行管理。

    注2:企业微信安全策略升级,企业微信在userId换取用户信息的接口中,不再返回手机号码。

             因此2022-06-20之后新建的应用不推荐使用手机号匹配,可以使用微信号匹配等其他匹配方式的功能,但老的应用不受影响。

    注3:切换了匹配方式后,都需要同步一下用户。

    25.png

    1)微信号/手机账号匹配

    微信号匹配手机号匹配展示列相同。

    微信号匹配,则是微信成员名与报表里用户名匹配,为一对一匹配。

    手机号匹配,微信用户的手机号是唯一的,但是报表用户可以设置多个用户有同一个手机号,此时的匹配逻辑为哪个报表用户先创建则匹配哪个

    选择这两个匹配方式时,微信通讯录信息展示:「微信成员名」、「姓名」、「微信部门」和「微信成员手机号」,如下图所示:

    26.png

    注:这些匹配的用户信息并不会存到某张表里。

    2)手动匹配

    当匹配方式为「手动匹配」时,微信成员列表中多出「报表用户名」一列信息,点击出现下拉框,选择相应的报表用户名,进行手动匹配。如下图所示:

    注1:手动匹配时,报表用户名支持选择「不选」选项。

    注2:手动匹配方式是用户可以自由选择与微信用户匹配的报表用户,可实现多个微信用户匹配同一个报表用户。

    27.png

    3)自定义匹配

    即通过设置的「服务器数据集」,将对应数据列的微信用户和报表用户相匹配。若出现一个微信用户对应了多个报表用户的情况,默认匹配第一个报表用户

    选择自定义匹配时,下方多出「匹配设置」项,选择「数据集」、「微信用户名」及「报表用户名」,进行匹配。如下图所示:

    注:自定义匹配时,微信用户列填写的是微信用户名。

    28.png

    4.3.2 微信通讯录

    点击左侧「立即更新」按钮,立即更新通讯录内容。也可设置定时更新,点击「自动更新」按钮,弹出设置框,设置更新频率。如下图所示:

    注1:用户匹配方式为「微信号匹配」或「手机号匹配」时,如果用户增删改报表用户或者在后台增删改微信用户,需要手动同步通讯录更新。

    注2:用户匹配方式为「手动匹配」或「自定义匹配」时,如果用户增删改报表用户或者在后台增删改微信用户,无需更新同步。

    29.png

    4.3.3 用户同步

    报表版本 V11.0.2 ,微信管理插件版本 V11.0.54 之后,支持将企业微信通讯录的用户信息同步到「用户管理」界面中,保存到平台。

    用户同步配置详情请参见:同步用户

    注:微信用户的同步只是拿到微信用户信息表,为了后续跟报表用户表进行匹配关系的建立,微信用户的同步操作不会覆盖现有报表平台用户。

    1)同步配置

    在「用户管理」中进行「同步用户」,用户来源选择「从企业微信同步」,选中对应的微信应用,即可根据企业微信通讯录实现同步效果。

    注:「微信管理>成员管理」的通讯录手动更新和自动更新;「用户管理>同步用户」都能实现平台用户信息的更新。

    2022-01-21_15-19-28.png


    2)同步成功后,用户信息同步到平台。

    注:因为企业微信接口限制,所以无法同步密码,报表用户初始密码随机生成。如果用户在 APP 或 PC 端想通过账号密码登录,需点击 忘记密码 ,重置后才能登录。

    同步出现问题请参见:同步/导入用户常见问题

    2022-01-21_16-34-44.png

    3)同步触发方式

    同步类别同步设置方式详情
    手动同步用户管理>同步用户>从企业微信同步
    第一次同步企业微信用户信息
    用户管理>同步用户管理>立即同步对用户信息再次进行同步
    微信管理>成员管理>立即更新更新通讯录,并同步「用户管理」中的用户信息
    自动同步
    微信管理>成员管理>自动更新
    根据微信管理中设置的「自动更新」时间,自动更新通讯录,并同步「用户管理」中的用户信息

    注意事项:

    1)企业微信通讯录添加的用户,要保证姓名、账号、部门、手机号不为空;

    2)使用企业微信同步前,平台同步功能是打开的,且不能清空过同步数据;

    不满足以上两点,同步企业微信用户到平台会失败

    4)企业微信和平台同步字段的映射关系

    将企业微信中的成员信息,同步到「用户管理」中时,每条字段的映射关系。

    平台字段企业微信字段
    用户ID
    账号
    用户名账号
    姓名姓名
    密码

    因为企业微信接口限制,无法同步密码,所以初始密码随机生成;

    如果用户希望通过 APP 或 PC 端登录,需要 重置密码

    手机手机
    邮箱邮箱
    部门iddepartmentid
    部门名称部门
    无职务无职务
    角色id
    tagid
    角色名称标签

    5. 效果查看

    5.1 企业微信

    进入企业微信,点击「工作台」,点击「FineReport 微信集成」,该用户会看到自己权限内可以查看的目录,如下图所示:

    注:不建议在电脑版企业微信访问移动端模板。

    1588077514154849.jpg

    5.2 个人微信

    普通微信可以扫描二维码关注,在普通微信中即可出现一个企业号,可在企业号中查看主页内容或收到推送消息。

    1)在「通讯录」 Tab 页下点击「微工作台」,点击「微信邀请」,邀请关注,扫描二维码,即可加入此企业。如下图所示:

    30.png

    2)进入企业后,点击应用,看到的内容与是否勾选「在微信插件中始终进入主页」有关,如下图所示:

    1588078040677151.png

    • 若勾选在微信插件中始终进入主页,收不到推送消息。

    • 若不勾选「在微信插件中始终进入主页」,同时需要在「企业微信」>「我」>「设置」>「新消息通知」里关闭「仅在企业微信中接受消息」,则可收到推送消息,可以查看推送的内容和配置的自定义菜单,如下图所示:

    23.jpg

    6. 微信单点登录及权限控制

    6.1 单点登录

    在手机企业微信 App 里,您可以看到是不需要登录 FS,直接可以查看结果的。而如果您使用手机浏览器访问相同的报表,您会发现,是需要登录的。那是因为,将微信成员与报表用户关联后,通过微信企业应用进入查看报表时,在 FineReport 后台,我们会使用微信的 OAuth2.0 接口进行用户验证并获取对应微信成员名,然后关联报表用户并自动登录,从而实现微信单点登录。

    6.2 权限控制

    微信应用的菜单是在微信中管理,所以哪些成员可以看到的哪些报表这是在微信中控制。比如您可以创建多个报表应用,每个应用的查看权限选择不同的成员或组。

    用户在微信中打开报表,是否可以查看报表的内容,以及可以查看的数据这部分是在 FR 报表端控制的,控制方法与 PC 端是一样的,比如可以通过角色控制可查看的报表,可以在报表模板中通过 SQL 语句通过用户名过滤来实现不同用户看到的数据不同等等。

    7. 注意事项

    7.1 内网开放白名单

    在做微信集成时,有的客户为内网环境,不允许所有网页都能访问,但要确保对 qyapi.weixin.qq.com  这个域名开放访问权限。

    7.2 微信扫码登录报错

    问题现象:

    企业微信扫码登录,部分成员扫码后会报错,检查了该用户名,和企业微信名称一样;扫码出错的和正常的用户在权限配置上是一样的。

    报错.png

    问题原因:

    用户在平台没有绑定手机号。

    解决方案:

    1)可以先登录平台进行绑定手机号;

    2)或者在同步用户时(或者手动添加用户时)添加上手机号,即也要维护手机号信息。

    7.3 微信单点登录慢

    问题现象:

    微信单点从点击应用到显示目录,需要 3s 的时间。本地一般也是需要 3-4s 。

    问题原因:

    单点速度除了受网络、手机性能影响外,还受到数据传输和页面加载的 js 的影响。加载 H5 页面有如下几个耗时点:一是请求 js 资源,一个一般是 1 到 2 秒,然后浏览器把资源加载到内存,大概 200 毫秒,最后再把图形渲染出来也需要一些时间,导致页面加载缓慢。

    7.4 23001网络异常

    微信部署代理服务器时,插件日志出现 error 级别的日志报错,报错码为「23001」则是网络异常的问题。

    可以参考文档解决异常:代理服务器连接外网 3.1节。

    8. 微信集成问题处理

    1)环境是否配置好:微信钉钉集成环境准备

    2)使用工具排查出现的各类常见(单点登录失败、同步通讯录失败、消息推送失败)问题:微信钉钉调试工具微信钉钉推送/单点/同步失败通过日志定位

    3)「微信管理」页面的「应用管理」报错;定时调度消息推送报错;网络异常等:微信钉钉应用列表报错

    4)出现错误码,对照错误码找问题:微信钉钉错误码对照表


    附件列表


    主题: 移动端应用
    • 有帮助
    • 没帮助
    • 只是浏览
    中文(简体)

    鼠标选中内容,快速反馈问题

    鼠标选中存在疑惑的内容,即可快速反馈问题,我们将会跟进处理。

    不再提示

    10s后关闭

    联系我们
    在线支持
    获取专业技术支持,快速帮助您解决问题
    工作日9:00-12:00,13:30-17:30在线
    页面反馈
    针对当前网页的建议、问题反馈
    售前咨询
    采购需求/获取报价/预约演示
    或拨打: 400-811-8890 转1
    qr
    热线电话
    咨询/故障救援热线:400-811-8890转2
    总裁办24H投诉:17312781526
    提交页面反馈
    仅适用于当前网页的意见收集,帆软产品问题请在 问答板块提问前往服务平台 获取技术支持