ftech-web-sdk

ftech-web-sdk

本项目基于 qianqun 来实现智能客服，质检，辅助等页面的极易集成 APAAS 方案。 本项目提供便利的 JS SDK 接入，可以将智能客服，质检，辅助页面快速接入到业务系统中，可以避免传统 iframe 的页面引入方式的跨域，身份认证等业务开发，也可以避免代码直接引入带来的 JS、CSS 样式冲突。

1、安装

npm i @tencent/ftech-web-sdk

2、APAAS页面集成介绍

当前SDK目前仅服务于腾讯云小微产品，包括智能质检、智能辅助、交互式数智人、客服机器人、语音助手等产品。

• 1、智能客服页面-industryPlatform页面接入

  • 微应用改造
  • 配置平台配置
  • SDK引入

  智能客服页面快速链接

• 2、智能客服页面-smart-contact-cms

  • 微应用改造
  • 配置平台配置
  • SDK引入 智能客服页面快速链接

• 3、智能质检页面

  • 微应用改造
  • 配置平台配置
  • SDK引入 智能质检页面快速链接

• 4、智能辅助页面

  • 微应用改造
  • 配置平台配置
  • SDK引入 智能辅助页面快速链接

3、接入流程

设计架构

1、vue 引入

import FtechWebSDK, { MicroApp } from '@tencent/ftech-web-sdk';

// 在页面初始化，调用 initial 接口获取 相关页面信息
const pageInfos = FtechWebSDK.initial({
  app_id: 'xxx', // 需要申请的app_id
  prefetch: true, // 是否预加载
  signUrl: isProd ? 'https://uni.xiaowei.cloud.tencent.com/api/common/getTestSign' : 'https://uni.xiaowei.cloud.tencent.com/test/api/common/getTestSign', // 参考 FAQ 如何实现
});

在对应页面容器中，启动该页面的加载过程。

<template>
  <div
    :style="{ height: visible ? 'auto' : 0 }"
    class="micro-app-wrapper"
    :class="{
      hidden: !visible,
    }"
  >
    <div v-show="loading && visible" class="micro-app-loading">
      <a-spin :spinning="loading" />
    </div>
    <div
      id="micro-app-container"
      :class="{
        'has-outset': isInNoBreadcrumbContainer,
      }"
    ></div>
  </div>
</template>
<script lang="ts">
import FtechWebSDK, { MicroApp } from '@tencent/ftech-web-sdk';
import Vue from 'vue';
export default Vue.extend({
  name: 'Container',
  data() {
    return {
      loading: false,
      microInstance: {} as MicroApp,
      pages: [],
    };
  },
  props: {
  },
  computed: {
    visible() {
      // 开始控制当前组件是否显示
      console.log('computed visible', this.$router);
      return location.hash.endsWith('/qa_pairs/all/all');
    },
  },
  beforeDestroy() {
    console.log('开始执行销毁逻辑', this.microInstance);
    this.microInstance?.unmount?.();
  },
  updated() {
    console.log('开始执行更新逻辑', this.microInstance);
    this.microInstance?.update?.({ ...props });
  },
  async mounted() {
    console.log('开始执行创建逻辑');
    FtechWebSDK.subscribe((value: any) => {
      console.log('监听子应用抛出事件', value);
    });
    const info: any = await FtechWebSDK.initial({
      app_id: 'xxx', // 需要申请的app_id
      prefetch: true, // 是否预加载
      signUrl: isProd ? 'https://uni.xiaowei.cloud.tencent.com/api/common/getTestSign' : 'https://uni.xiaowei.cloud.tencent.com/test/api/common/getTestSign', // 参考 FAQ 如何实现
    });
    this.microInstance = await FtechWebSDK.load({
      pageId: info.appId,
      container: '#micro-app-container',
      props: {
        loginUrl: '', // 腾讯登录之后的重定向地址, 默认指向当前页面地址
        baseApiUrl: info.apiBaseUrl,
        useNativeRoute: 3, // 具体参考 FAQ 如何决定采用何种路由方式去加载微应用？
      },
    }, configration?);
  },
});
</script>

<style lang="less" scoped>
#micro-app-container {
  height: 100%;
  overflow: auto;

  .has-outset {
    margin: -16px -20px;
  }
}

#micro-app-container > div {
  height: 100%;
}

.micro-app-wrapper {
  &.hidden {
    display: none;
  }

  .micro-app-loading {
    height: 100%;
    width: 100%;
    display: inline-flex;
    align-items: center;
    justify-content: center;
  }
}
</style>

2、react 引入

待补充

4、参数文档

initial(appInfo) 接口

appInfo参数列表：

{
  app_id: 'xxx', // 需要申请的app_id
  prefetch: true, // 是否预加载
  signUrl: 'remote-url', // 参考 FAQ 如何实现
}

返回值：

{
  "appId":"001",
  "appName":"问答知识库",
  "appUrl":"https://xiaowei.cloud.tencent.com/chatbot/",
  "path":"/#/products/2a_1645433697270_40/-/qa_pairs/all/all",
  "apiBaseUrl":"https://uni.xiaowei.cloud.tencent.com/chatbot/api",
  "platform":"industry"
}

load(FloadConfig) 接口

FloadConfig 参数列表

interface FLoadConfig {
  container: string;
  pageId: string;
  props?: FMicroProps; // 传入对应微应用所需要的参数
}

返回 MicroApp 实例：

• mount(): Promise;
• unmount(): Promise;
• update(customProps: object): Promise;
• getStatus(): | "NOT_LOADED" | "LOADING_SOURCE_CODE" | "NOT_BOOTSTRAPPED" | "BOOTSTRAPPING" | "NOT_MOUNTED" | "MOUNTING" | "MOUNTED" | "UPDATING" | "UNMOUNTING" | "UNLOADING" | "SKIP_BECAUSE_BROKEN" | "LOAD_ERROR";
• loadPromise: Promise;
• bootstrapPromise: Promise;
• mountPromise: Promise;
• unmountPromise: Promise;

详情参考参考 qiankun官方文档

subscribe(callback: (value: FMicroEvent) => void): Unsubscribe

监听主子应用的事件和数据，callback 函数({ type: string; data: any }) => { 处理程序 } 目前通用返回加载完成事件 type: load，其他自定义事件由主子应用自行定义。

返回值：返回取消订阅的句柄。

5、FAQ

1、如何实现生成秘钥的算法？

实例代码-Node.js

const crypto = require('crypto');
/**
 * @params options: https request body
 * @params apiAppKey: 申请APAAS页面接入时生成的app_key, 请妥善保存
 * @params apiAppSecret: 申请APAAS页面接入时生成的secret, 请妥善保存
 * @return authorization: 生成的秘钥串
 * @return dateTime: 服务器当前时间
*/
interface GetAuthorizedHeaderProps {
  options: {
    method: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'OPTIONS';
    headers: {
      Accept: string;
      'Content-Type': string;
      'Content-MD5': any;
    };
    path: string;
  };
  apiAppKey: string;
  apiAppSecret: string;
}
// 生成秘钥的主函数
export const getAuthorizedHeader = ({ options, apiAppKey, apiAppSecret }: GetAuthorizedHeaderProps) => {
  const dateTime = new Date().toUTCString();
  const signingStr = [
    `x-date: ${dateTime}`,
    options.method,
    options.headers.Accept,
    options.headers['Content-Type'],
    options.headers['Content-MD5'],
    options.path,
  ].join('\n');
  const signing = crypto.createHmac('sha1', apiAppSecret).update(signingStr, 'utf8').digest('base64');
  const sign = `hmac id="${apiAppKey}", algorithm="hmac-sha1", headers="x-date", signature="${signing}"`;
  return {
    authorization: sign,
    dateTime,
  };
};

其他语言DEMO待补充

2、如何决定采用何种路由方式去加载微应用？

主应用 xxx.qq.com/chatbot/ 对于即将集成进来的页面，例如云小微智能客服页面，其本身采用的是 vue-router/Hash 模式，因此引入其页面时必须适配其路由模式。 目前 SDK 在加载页面时，提供了三种路由适配模式，来应对不同场景的引入，

1、useNativeRoute = 0 采用配置端数据返回的路由路径 2、useNativeRoute = 1 采用当前页面hash前缀 + 配置端数据返回的路由路径作为新路由 3、useNativeRoute = 3 采用当前的页面路由不做任何改动， 默认 0

这里以具体例子来讲解。

主应用要集成云小微智能客服/问答知识库页面，其hash地址是#/products/2a_1642564944681_44/-/qa_pairs/all/all。

主应用如果采用后台返回的注册路径，即 useNativeRoute = 0，其页面路径会被替换成 xxx.qq.com/chatbot/#/products/2a_1642564944681_44/-/qa_pairs/all/all, 比较适用于主应用采用的 history 模式或者配置端直接接入的方式，不用关心路径中的参数配置，也是最推荐的模式。

主应用如果采用后台返回的注册路径，即 useNativeRoute = 1，引入页面已经存在了hash的部分路径#/jce，其页面路径会被替换成 xxx.qq.com/chatbot/#/jce/products/2a_1642564944681_44/-/qa_pairs/all/all, 比较适用于主应用采用的 hash 模式, 且页面路由要求存在特定前缀。这种模式能够保证同一页面能够被多次引入，且不干预主应用路由配置。

主应用如果采用后台返回的注册路径，即 useNativeRoute = 3，就是不对当前路由进行任何修改，采用主应用的路由来让子应用进行自行解析，比较适合和微应用同源的主应用进行引入。