@beeworks/imsdk IM JS-SDK

本文档说明 SDK 的两种典型使用方式：

1. 通过 <script> 标签直接在浏览器中引入
2. 通过 npm 安装，在 Vite 或 Webpack 等现代前端工程中使用

一、通过 <script> 标签引入

1. 部署文件

将构建产物中的文件部署到静态资源目录，例如：

• imsdk.1.0.0.js：打包好的 UMD 版本，版本号以实际使用版本为准
• imsdk.wasm：Go 编译生成的 WebAssembly 文件
• sql-wasm.wasm: sql.js 核心 WebAssembly 文件（用于本地数据库功能）

推荐将两者放在同一目录，例如：

• /static/sdk/imsdk.1.0.0.js
• /static/sdk/imsdk.wasm
• /static/sdk/sql-wasm.wasm

2. 在页面中引入并初始化

<script src="/static/sdk/imsdk.1.0.0.js"></script>
<script>
  const { init, login, EVENT } = window.imsdk;

  async function bootstrap() {
    const ok = await init({
      appId: 'your-app-id',
      wasmUrl: '/static/sdk/imsdk.wasm',
      sqlWasmUrl: '/static/sdk/sql-wasm.wasm',
      wsUrl: 'wss://example.com/im',
      httpUrl: 'https://example.com/app',
      debug: true,
    });

    if (!ok) {
      console.error('IM SDK init failed');
      return;
    }

    await login({
      userId: 'user-1',
      token: 'your-jwt-token',
    });
  }

  bootstrap();
</script>

说明：

• 加载脚本后，全局会挂载 window.imsdk，包含：
  • init, login, logout, connect, disconnect 等方法
  • EVENT, TYPES 等常量
• wasmUrl：
  • 推荐显式传入完整 URL（如上例）
  • 如果省略该字段，SDK 会使用默认值 "./imsdk.wasm"，相对于当前页面 URL
• sqlWasmUrl：
  • 用于加载 sql.js 功能的 WASM 文件
  • 推荐显式传入完整 URL（如上例）
  • 如果省略该字段，SDK 会使用默认值 "./sql-wasm.wasm"，相对于当前页面 URL

二、通过 npm 安装（结合 Vite / Webpack）

首先在工程中安装 SDK：

npm install @beeworks/imsdk

1. 在 Vite 项目中使用

Vite 原生支持通过 ?url 的方式导入任意静态资源，并在构建时自动复制到 dist/assets。

示例（React / Vue / 其他框架项目类似）：

import { init, login, EVENT } from '@beeworks/imsdk';
import wasmUrl from '@beeworks/imsdk/dist/imsdk.wasm?url';
import sqlWasmUrl from '@beeworks/imsdk/dist/sql-wasm.wasm?url';

async function bootstrap() {
  const ok = await init({
    appId: 'your-app-id',
    wasmUrl,
    sqlWasmUrl,
    wsUrl: 'wss://example.com/im',
    httpUrl: 'https://example.com/app',
    debug: true,
  });

  if (!ok) {
    console.error('IM SDK init failed');
    return;
  }

  await login({
    userId: 'user-1',
    token: 'your-jwt-token',
  });
}

bootstrap();

要点：

• import wasmUrl from '@beeworks/imsdk/dist/imsdk.wasm?url'
  • Vite 会在打包时自动复制 imsdk.wasm 到输出目录，并返回构建后的 URL 字符串
• import sqlWasmUrl from '@beeworks/imsdk/dist/sql-wasm.wasm?url'
  • Vite 会在打包时自动复制 sql-wasm.wasm 到输出目录，并返回构建后的 URL 字符串
• 不需要手动拷贝 wasm 文件
• 其余调用方式与 script 引入基本一致

2. 在 Webpack 5 项目中使用

Webpack 5 可以使用内置的资源模块（asset modules）来处理 wasm 文件。

配置 Webpack

在 webpack.config.js 中添加规则：

module.exports = {
  // ...
  module: {
    rules: [
      {
        test: /(imsdk|sql-wasm)\.wasm$/,
        type: 'asset/resource',
      },
    ],
  },
};

在代码中使用

import { init, login } from '@beeworks/imsdk';
import wasmUrl from '@beeworks/imsdk/dist/imsdk.wasm';
import sqlWasmUrl from '@beeworks/imsdk/dist/sql-wasm.wasm';

async function bootstrap() {
  const ok = await init({
    appId: 'your-app-id',
    wasmUrl,
    sqlWasmUrl,
    wsUrl: 'wss://example.com/im',
    httpUrl: 'https://example.com/app',
  });

  if (!ok) {
    console.error('IM SDK init failed');
    return;
  }

  await login({
    userId: 'user-1',
    token: 'your-jwt-token',
  });
}

bootstrap();

Webpack 会在打包时：

• 将 imsdk.wasm 和 sql-wasm.wasm 拷贝到构建输出目录（具体路径取决于 output.assetModuleFilename 配置）
• 将 wasmUrl 和 sqlWasmUrl 替换为构建后的实际访问 URL

三、其他说明

SDK 内部已经将 Go 官方的 wasm_exec.js 运行时代码打包进主 bundle，使用者无需单独引入该文件。