Engage 开放平台文档

# 一、什么是应用？

在 Engage 平台中，应用（App）是一个核心概念。它表示一个可独立部署、可嵌入 Engage 系统界面、可供租户购买的这么一个实体。它跟我们平时开发的系统没什么区别，一样可以有前端界面、后端接口、数据库，一样在自己所控制的服务器或环境内部署（不会部署到 Engage 所在环境内）——区别仅在于前端界面和后端接口需要做一定的适配来集成到 Engage 平台中。

# 应用开发的一些说明与约束

  • 后端架构无所谓，不管是 Java、还是 NodeJS，也不管数据库是 MySQL 还是 PostgreSQL，都是可以的。因为本质上后端还是部署在你自己的服务器内，Engage 是不会管也无法管的。但后端在与 Engage 通信时，必须使用 HTTPS + JSON 方式。
  • 前端可以使用 Pure JavaScript + HTML，也可以使用 Vue 开发。理论上也支持 React。前端需要按照微前端的方式做一定的架构调整，但不对本身业务层带来太大影响。
  • 如果要保持跟 Engage 的交互方式较为统一，需要使用 Engage 组件库，并且接受组件库对后端接口的规范约束。

# 二、创建应用

在开发应用之前，我们需要先在 Engage 平台中申请一个应用，主要是为了获取 Open Api 的相关凭据。

  1. 前往 Engage Admin 系统，进入应用管理，点击新建应用
  2. 依次填入版本号（比如 1.0.0）、应用配置（yaml 格式）、应用 Icon、应用摘要、更新说明、应用描述
  3. 应用配置中，填写 id、name 属性，分别对应应用 Id 和应用中文名称。id 务必全小写，单词之间用 - 连接。
  4. 接着填写 micro-front-ends 的 id，改为 mfe-<应用 Id>
  5. 其他配置此时暂时不用管，详细说明可参考文档 应用配置手册
  6. 点击弹出框右下角的”暂存“按钮，回到列表页。
  7. 刷新界面，找到新创建的应用，点击其名称，在右侧浮出框中可以看到三个关键字段：client_id、client_secret、client_sign。这是应用后续与 Engage 平台进行通信的密码，务必谨慎存放。

# 三、开发应用

示例应用代码可参考：https://gitlab.gridsum.com/engage/sample-app ，其中 sample-app-java-api 对应的是应用后端的 OpenAPI 和 Inner API 网关，sample-app-java-svc 为实际业务接口的实现，sample-app-mfe 为应用前端工程,对应的界面地址为 https://alpha-engage.gridsumdissector.com/platform/sample-app。

代码访问请向 Engage 团队提出申请；界面访问请先向 SSO 申请访问 GCRM 产品，然后向 Engage 申请访问 Engage 系统。

# 应用后端：Open API

Engage 应用有两种接口概念，一种是 Open API，用于跟其他应用（包括平台）之间进行通信，一种是 Inner API，用于跟应用自身的前端页面进行通信。Open API 开发与使用请参考 Open API，这个我们可以稍后在细看。

应用需要固定实现几个 Open API，用于应用发布时跟平台之间的身份确认与服务可用性测试。假定应用的 Open API 网关地址为 https://app1.com/open-api，应用需要提供的基本 Open API 接口说明如下：

  • https://app1.com/open-api/v1/identify：应用识别接口。应用在发布时，平台会发起该接口调用，传入的是一个 32 位的随机字符串。应用需要在收到请求后，解密验签，然后将该 32 位长度的字符串进行翻转。再对翻转后的字符串做加密签名后返回。平台收到后确认无误，则表明应用正确实现了 Open API 的加解密、签名功能。
  • https://app1.com/open-api/v1/profile/bind：租户购买应用接口。租户在 Engage 平台的应用商店中，下单购买本应用时，平台会调用该接口。接口入参包括租户 Id、名称、购买版本（Plan）、购买时长等信息，应用收到请求后，可以在本应用中记录租户信息，执行一些必要的初始化工作。响应为空即可。
  • https://app1.com/open-api/v1/addons/identify：插件注入与校验接口。如果本应用有功能可供别的应用定制、扩展——即插槽，则需要实现此接口。当别的应用发布时，如果其应用配置中声明了要给本应用注入插件，则平台会把这些插件的配置信息发到此接口。一个插件配置包括目标应用、类型（与版本）、配置参数等。应用可以对这些插件进行校验，检查其配置是否正确。还可以以此信息为基础，做一些初始化的准备工作。

# 应用后端：Inner API

Inner API 是应用前端调用的应用内 HTTP 接口。这里没有什么太多的改造内容，唯一要注意的是会话的处理方式。

由于用户是在 Engage 平台登录的，所以 Cookie 只在 Engage 平台的域名下，Inner API 所在的域名是无法访问该 Cookie 的。Engage 会生成一个 User Token，代表当前登录会话。使用方式：

  1. 前端在发起 Inner API 调用时，取出存放在 window['engage-common'].engage.estore.userToken（也可以通过 require('engage').estore.userToken 来获取）的 User Token。
  2. 可以将 User Token 作为 URL Query 或 HTTP Header 传递给后端
  3. 应用后端从 URL Query 或 Header 中取出 User Token，调用 Engage 平台的用户会话查询（/v1/user-token/info）Open API，获取该 Token 对应的用户 Id、名称、租户 Id、当前岗位 Id 等信息。
    • 应用后端应该对 User Token 查询结果进行缓存（避免过于影响接口响应速度）。但缓存时间不宜过长，推荐 30 秒。过长时间不被允许，因为会带来安全隐患。
  4. 拿到岗位后，调用 Engage 平台的岗位应用内接口权限查询（/v1/app-resource/info）Open API，获取当前岗位可以访问的所有 API 列表。并判断当前请求的路径是否在列表中，如果在表示可以访问，不再表示没有权限访问（通常返回 403 HTTP 状态码）
    • 岗位的接口列表通常也要缓存，推荐在 60 秒左右，或稍微再延长一些。
    • 由于角色所包含的接口是前缀匹配模式，所以在这里也是要按前缀来匹配请求的路径是否在岗位接口列表中。

应用后端不需要创建 Cookie 用来标识用户的登录状态，这样会产生行为不一致以及安全隐患（比如用户从 Engage 退出登录后，还能照常访问 Inner API）。

# 应用前端：MFE

一个应用不必定然包含前端。但包含前端的应用，则需要进行微前端改造。在 Engage 的界面中，用户看到的是浑然一体的内容，不是通过 iframe 或浏览器窗口来分裂展示的内容。即在微前端技术的改造下，用户不会对 Engage 产生是由多个”传统系统“所构成的印象。所有的前端界面都是一个 window 对象下的 JS 渲染的。

要将现有的前端工程改造成微前端，不会太难。如果是 Vue 开发的，搭配 Engage FE CLI 工具改造则更加简单。最主要的改造有以下几点：

  1. 不再是 new Vue() 来在 JS 加载后立即渲染页面了，而是由微前端引擎来根据 URL 适时调度，执行渲染。
  2. 不再需要引入 vue、vue-router、vuex 这些依赖了，因为平台在运行时可以提供它们
  3. 只支持更加美观、现代的 History 模式的路由，不再支持 Hash 模式
  4. URL 要保证全局唯一，所以最好以应用 Id 为前缀

具体改造细节可参考 使用 Engage FE CLI 改造现有 Vue 前端工程。

如果要使用 Engage 组件库开发，可以参考 组件设计与手册

# 四、发布应用

应用开发完毕并在自己的服务器或环境内部署成功后，接下来要在 Engage 平台上进行发布。进入 Engage 后台系统，进入应用管理页面，点击之前创建（暂存）的应用，在指定版本上点击发布，在弹出框中进行必要信息的填写。

发布应用时，平台会调用应用识别接口和插件注入与校验接口。如果都没问题，则发布成功，可以接受租户的购买了。

更多使用案例可参考 应用配置手册。

← 快速搭建前端工程 →