Web SDK 集成指南

更新时间 2025/01/04 07:34:18

欢迎使用我们的 Web SDK 来扩展和增强您的应用功能。本指南将引导您完成 SDK 的集成过程，包括安装、配置、初始化以及如何使用 SDK 提供的主要功能。

准备工作

在开始之前，请确保您已完成了集成准备中列出的所有步骤。

第一步：安装 sdk 所需依赖项

我们的 Web SDK 除了核心功能外，还依赖于一些第三方库以确保最佳性能。在安装 SDK 之前，请确认您的项目中也安装了这些必要的 peerDependency。

npm install react@^17.0.2 react-dom@^17.0.2 agora-rtc-sdk-ng ali-oss

React 版本兼容性

我们的 Web SDK 设计时基于 React v17 构建，以确保最佳性能和稳定的功能体验。如果您的应用环境中已经安装了不同版本的 React（如 v18），可能会遇到兼容性问题。

确认项目中的 React 版本

在集成 SDK 之前，请检查您的项目依赖，并确认是否使用的是 React v17。您可以通过查看 package.json 文件或运行以下命令来检查已安装的 React 版本：

npm list react

如果发现版本不符，则需要考虑采取适当措施以防止潜在的冲突。 一种可行的方式为使用 iframe 机制来隔离 SDK：

• 在您的网页中创建一个新的 iframe 标签。
• 将 iframe 的源设置为托管您 SDK 集成页面的地址。
• 通过 postMessage API 进行父页面与 iframe 内部页面之间的消息传递。

实施隔离机制后，您可以在 iframe 中使用 SDK，同时保持主应用与 SDK 应用环境的独立性，确保两者互不影响。

第二步：安装 SDK

通过 npm 安装我们的 Web SDK 到您的项目中：

npm install @plaso-infi/whiteboard-sdk

第三步：引入 SDK

在您的 JavaScript/TypeScript 代码中引入 SDK 模块：

import InfiWebSdk from '@plaso-infi/whiteboard-sdk';
// 需要引入画布样式文件，此文件有做类命名 scoped 处理，所以不用担心样式名称冲突
import '@plaso-infi/whiteboard-sdk/dist/esm/index.css';

第四步：初始化 并配置 SDK

// 初始化画布实例
const initPromise = await InfiWebSdk.getSdkInstance({
  /**
   * getQuery 函数为获取画布连接参数的函数，我们推荐您在服务端生成画布连接参数，以避免
   * appKey 在网络上传输。
   */
  getQueryString: getQuery,
  /**
   * 给入画布用户的信息，包括用户ID loginName，与用户名称 userName。
   * 对于不同用户，loginName 应尽可能保证不同，而 userName 则只会影响显示
   */
  userInfo: {
    loginName: 'USER_UUID',
    userName: 'USER_DISPLAY_NAME',
  },
  /** 给入画布即将挂在的 DOM 节点 */
  containerDom: container,
  /**
   * 画布用来根据用户 loginName 读取远端用户数据，并用户本地显示的函数，
   * 如果为单人使用画布情况，如下传入空函数即可
   */
  getUsersInfo: async () => [],
});

/**
 * 检查画布初始化的结果：
 * - code 为 0 时，表示初始化成功，此时 payload 为 Web SDK 实例对象
 * - code 不为 0 时，表示初始化失败，此时 payload 为错误消息提示字符串
 */
const { code, payload: sdk } = initPromise;

第五步：使用 SDK

现在您可以使用 SDK 提供的各种功能了，比如创建画布、添加元素或者监听事件：

// 监听事件
sdk.on('connected', () => { ... });

// 插入元素
sdk.insertImage(...)

第六步：部署和测试

将集成了 SDK 的应用部署到测试环境中，并进行全面的功能与性能测试。