im2-link-jssdk

v1.4.3

Published

11 days ago

`im2-link-jssdk` 是 H5 小程序与宿主 App/WebView 之间的通信 SDK。Web 侧通过统一 API 请求宿主完成支付、导航、系统分享、下载、网络请求等原生能力；SDK 负责平台识别、消息封装和回调分发。

0High
0Medium
0Low

mzkxz

im2-link-jssdk

im2-link-jssdk 是 H5 小程序与宿主 App/WebView 之间的通信 SDK。Web 侧通过统一 API 请求宿主完成支付、导航、系统分享、下载、网络请求等原生能力；SDK 负责平台识别、消息封装和回调分发。

本 README 以当前源码为准：公开方法、参数类型、消息类型和回调协议均与 src/index.ts、src/types/common.ts 保持一致。

在线文档

以上地址指向 npm 当前已发布版本的类型文档。仓库中的最新改动会在下次发布后同步到这两个地址。

安装

npm install im2-link-jssdk

SDK 同时提供 ESM、CommonJS 和 TypeScript 类型声明。

快速开始

import IMSDK from 'im2-link-jssdk';

const sdk = new IMSDK({
  id: 'your-app-id',
  token: 'your-app-token',
  debug: false
});

sdk.share({
  type: 'system',
  param: {
    title: '分享标题',
    text: '分享描述',
    shareUrl: 'https://example.com?share_source=tg',
    imageUrl: 'https://example.com/share.png'
  }
});

初始化参数：

| 参数 | 类型 | 必填 | 说明 | | ------- | --------- | ---- | ----------------------------------- | | id | string | 是 | 小程序 App ID | | token | string | 是 | 小程序 App Token | | debug | boolean | 否 | 是否打印 SDK 调试日志，默认 false |

H5 小程序要求

使用 Webpack、Rspack 或其他可输出浏览器资源的构建工具。
使用 Hash 路由，路由状态由 window.location.hash 承载。
构建入口文件命名为 index.html。
发布时将构建产物打包为 ZIP。
SDK 依赖浏览器的 window 和 navigator，不要在 SSR 服务端执行初始化。

API 概览

| API | ---------------------- | platform | callPayment | callBack | callConversation | callNavigate | permissions | callOpenMiniProgram | callSetBarColor | callPopup | requestApi | requestApp | adjustInputBoxHeight | switchLandscape | share | download | behaviorCaptcha | getCaptchaAccount | vibrate | 宿主消息类型 | 用途 | | ----------------- | ------------------------ | | - | 获取当前运行平台 | | payment | 拉起原生支付 | | back | 通知宿主返回 | | conversation | 打开指定用户会话 | | navigate | 调用宿主导航 | | permissions | 请求宿主权限能力 | | openminiapp | 打开其他小程序 | | barcolor | 设置状态栏颜色 | | popup | 拉起原生弹框 | | requireAPI | 由宿主发起网络请求 | | requireAPP | 与宿主交换业务数据 | | inputBoxHeight | 调整输入框高度 | | landscape | 切换横屏状态 | | share | 业务分享或系统分享 | | download | 请求宿主下载视频 | | behaviorCaptcha | 发送行为验证码结果 | | captchaAccount | 索取登录页账号与区号 | | vibrate | 触发宿主系统振动 |

平台信息

const platform = sdk.platform;

返回值为：

type Platform = 'win' | 'mac' | 'unix' | 'linux' | 'android' | 'ios' | 'unknown';

支付

import { IMChainCurrencyEnum } from 'im2-link-jssdk';

sdk.callPayment(
  {
    amount: '99.00',
    consumeType: 'goods',
    chainCurrencyType: IMChainCurrencyEnum.CNY,
    productOrderNo: 'ORDER-20260828-001',
    productName: '商品名称',
    quantity: '1'
  },
  (isSuccess) => {
    console.log('支付是否成功：', isSuccess);
  }
);

chainCurrencyType 可选值：CNY = 1、KKC = 2、VNC = 3。

支付参数可以省略；省略时表示只校验支付密码：

sdk.callPayment(undefined, (isSuccess) => {
  console.log('支付密码校验结果：', isSuccess);
});

当初始化的 id 不等于字符串 '0' 时，SDK 会先校验 App ID 和 App Token，再向宿主发送支付消息。校验失败只会输出 callPayment error，不会继续拉起支付。

callPayment 是当前唯一返回 Promise<void> 的公开方法。等待该 Promise 只表示前置校验和消息发送结束，支付最终结果仍以回调为准。

返回、会话与导航

sdk.callBack(() => {
  console.log('宿主已处理返回');
});

打开会话

sdk.callConversation('target-user-open-id', () => {
  console.log('宿主已处理会话请求');
});

宿主导航

sdk.callNavigate(
  {
    actionType: 'external',
    params: {
      route: 'https://example.com'
    }
  },
  () => {
    console.log('宿主已处理导航请求');
  }
);

当前约定的 actionType 包括：

| 值 | 用途 | | ------------------ | --------------------------------- | | home | 首页 | | channel | 超级群，params 中传 channelId | | trad | 交易页面 | | inner | 内部链接，params 中传 route | | external | 外部链接，params 中传 route | | invite | 邀请页面 | | share | 系统分享入口 | | shortVideoSearch | 短视频搜索 | | customerService | 客服页面 |

actionType 在当前类型定义中是 string，表格列出的是宿主已约定的业务值。

权限

sdk.permissions(
  {
    actionType: 'camera'
  },
  (result) => {
    console.log('权限结果：', result);
  }
);

params 当前使用 IMNavigateParams 结构，实际 actionType 及返回数据由宿主约定。

打开小程序

sdk.callOpenMiniProgram(
  'miniapp://target-app',
  {
    source: 'current-app',
    scene: 'detail'
  },
  () => {
    console.log('宿主已处理打开请求');
  }
);

第二个参数为可选的透传对象。若不需要透传参数，可传 undefined：

sdk.callOpenMiniProgram('miniapp://target-app', undefined, () => {
  console.log('宿主已处理打开请求');
});

状态栏与原生弹框

设置状态栏颜色

sdk.callSetBarColor(
  {
    titleColor: '#FFFFFF',
    backgroundColor: '#1677FF'
  },
  () => {
    console.log('颜色设置完成');
  }
);

titleColor 和 backgroundColor 均为可选字符串，颜色格式由宿主解析。

拉起原生弹框

sdk.callPopup(
  {
    url: 'https://example.com/popup',
    ratio: 0.75,
    popupType: 2
  },
  () => {
    console.log('弹框已处理');
  }
);

popupType：

| 值 | 展示方式 | | --- | -------------- | | 1 | 带标题栏 | | 2 | 居中弹出 | | 3 | 从底部向上覆盖 |

网络请求与 App 数据交互

由宿主发起网络请求

interface UserProfile {
  id: string;
  nickname: string;
}

sdk.requestApi<UserProfile>(
  {
    type: 'core',
    url: '/v1/user/profile',
    method: 'GET',
    param: {
      userId: '10001'
    }
  },
  (data) => {
    console.log(data.nickname);
  }
);

参数说明：

| 参数 | 类型 | 必填 | 说明 | | -------- | --------------------- | ---- | ---------------------------- | | type | 'core' \| 'wallet' | 否 | 请求服务类型，默认 'core' | | url | string | 是 | 请求地址 | | method | string | 是 | 请求方法，例如 GET、POST | | param | Record<string, any> | 否 | 请求参数 |

与宿主交换业务数据

sdk.requestApp<{ url: string }>(
  {
    method: 'h5-register',
    param: {
      locale: 'zh-CN'
    }
  },
  (data) => {
    console.log('注册页面：', data.url);
  }
);

method 和 param 由 Web 与宿主共同约定；当前已记录的方法为 h5-register。

WebView 布局与方向

调整输入框高度

sdk.adjustInputBoxHeight(320, (result) => {
  console.log('调整结果：', result);
});

高度单位和结果数据由宿主约定。

切换横屏

sdk.switchLandscape(true, (result) => {
  console.log('切换结果：', result);
});

第一个参数默认值为 true；传 false 表示取消横屏。

share 通过 type 区分短视频、棋牌游戏和系统分享。

短视频分享

sdk.share(
  {
    type: 'shortVideo',
    param: {
      cover_url: 'https://example.com/cover.jpg',
      description: '视频描述',
      title: '视频标题',
      user_id: '10001',
      video_id: 'video-001'
    }
  },
  (result) => {
    console.log('分享结果：', result);
  }
);

棋牌游戏分享

sdk.share(
  {
    type: 'cardGame',
    param: {
      show_type: 3,
      game_path: '/room/10001',
      game_preview_width: 375,
      game_preview_height: 667,
      game_preview_url: 'https://example.com/game-preview',
      currencySource: 'CNY',
      subGameName: {
        ch: '游戏名称',
        en: 'Game name'
      }
    }
  },
  (result) => {
    console.log('分享结果：', result);
  }
);

show_type 的含义：0 为默认旧样式，1 为不带链接的棋牌游戏样式，2 为带链接的棋牌游戏样式，3 为游戏预览。

系统分享

sdk.share({
  type: 'system',
  param: {
    title: '分享标题',
    text: '分享描述',
    shareUrl: 'https://example.com?share_source=tg',
    imageUrl: 'https://example.com/share.png'
  }
});

所有字段均为必填字符串：

| 字段 | 说明 | | ---------- | ---------------------------------------- | | title | 分享标题 | | text | 分享描述 | | shareUrl | 分享链接；游戏分享来源参数 share_source=tg 拼在此链接中 | | imageUrl | 分享图片 URL；宿主下载图片后用于图文分享 |

宿主收到的消息如下：

{
  "type": "share",
  "params": {
    "type": "system",
    "param": {
      "title": "分享标题",
      "text": "分享描述",
      "shareUrl": "https://example.com?share_source=tg",
      "imageUrl": "https://example.com/share.png"
    }
  },
  "appid": "your-app-id",
  "apptoken": "your-app-token"
}

系统分享与其他 share 类型一样，可以传入可选回调。

下载

sdk.download(
  {
    fileType: 'video',
    url: 'https://example.com/video.mp4'
  },
  (result) => {
    console.log('下载结果：', result);
  }
);

当前 fileType 仅支持 'video'。

行为验证码

sdk.behaviorCaptcha(
  {
    token: 'captcha-result-token'
  },
  () => {
    console.log('验证码结果已发送给宿主');
  }
);

此 API 用于 H5 完成滑动验证后，将验证码 token 透传给宿主。

验证码 token 获取失败时，也可沿用同一通道透传上游业务响应；SDK 不解析业务码或文案：

sdk.behaviorCaptcha({
  code: 1038,
  msg: '由业务服务返回的提示',
  data: {}
});

成功结果仍保持 { token }，以兼容既有 App。宿主可通过是否存在 params.token 区分成功与业务失败。

系统振动

H5 通过 vibrate 通知宿主调用设备系统振动 / 触觉反馈。未传参数时按短振动处理。

// 默认短振动
sdk.vibrate();

// 短振动，指定强度
sdk.vibrate({ type: 'short', style: 'heavy' });

// 长振动
sdk.vibrate({ type: 'long' }, (isSuccess) => {
  console.log('振动是否已触发：', isSuccess);
});

// 指定时长（毫秒），宿主按系统能力执行
sdk.vibrate({ duration: 200 });

参数说明：

| 参数 | 类型 | 必填 | 说明 | | ---------- | -------------------------------- | ---- | ------------------------------------------------------------ | | type | 'short' \| 'long' | 否 | 振动类型，默认 'short' | | style | 'light' \| 'medium' \| 'heavy' | 否 | 短振动强度，仅 type 为 'short' 时生效 | | duration | number | 否 | 振动时长（毫秒）。与 type 同时存在时，宿主优先按 duration 执行 |

宿主收到的消息如下：

{
  "type": "vibrate",
  "params": {
    "type": "short",
    "style": "heavy"
  },
  "appid": "your-app-id",
  "apptoken": "your-app-token"
}

iOS 建议将 short + style 映射为 UIImpactFeedbackGenerator，long 映射为系统振动；Android 建议使用 VibrationEffect。桌面端和无振动能力的设备可直接回 isSuccess: 0。

宿主接入协议

本节供 iOS、Android、桌面端和 H5 容器开发者实现消息桥接。

Web 回调语义

| API | Web 侧收到的回调值 | | -------------------------- | --------------------------------------------- | | requestApi、requestApp | 宿主返回的业务数据 | | permissions | 宿主返回的权限数据 | | 其他带回调的 API | isSuccess === 1 时为 true，否则为 false |

部分历史 API 的 TypeScript 回调签名为 () => void，调用方可以只把它当作完成通知；SDK 运行时仍会传入上述布尔结果。

Web 发给宿主的统一消息

interface SDKMessage {
  type: MessageTypeEnum;
  params?: unknown;
  callback?: string;
  appid: string;
  apptoken: string;
}

type：原生能力标识，见“API 概览”。
params：对应 API 的业务参数。
callback：调用方传入回调时由 SDK 生成；无回调时不发送该字段。
appid、apptoken：初始化 SDK 时传入的身份信息。

各平台发送通道

| 环境 | SDK 调用的宿主通道 | 消息形式 | | ---------------------- | ------------------------------------------------------------------- | ----------- | | iOS | window.webkit.messageHandlers.JSParent.postMessage(message) | 对象 | | Android | window.JSParent.postMessage(JSON.stringify(message)) | JSON 字符串 | | Windows / Unix / Linux | window.miniJSParent.postMessage(message) | 对象 | | macOS | 优先使用 webkit.messageHandlers.JSParent，否则使用 miniJSParent | 对象 | | H5 iframe | window.parent.postMessage(message, '*') | 对象 |

原生宿主返回回调

消息带有 callback 时，原生宿主处理完成后应调用对应的全局回调：

// 普通原生能力：payment、navigate、share 等
window.IMCallBack[callback](
  JSON.stringify({
    isSuccess: 1,
    callback
  })
);

// requestApi、requestApp
window.receiveData[callback](JSON.stringify(responseData));

// permissions
window.permissions[callback](JSON.stringify(permissionData));

IMCallBack 中 isSuccess 为 1 时，Web 回调接收 true；其他值接收 false。receiveData 和 permissions 的数据会先经过安全 JSON 解析，以避免大整数精度丢失。

H5 容器返回回调

父页面通过 postMessage 返回：

iframeWindow.postMessage(
  {
    type: 'IMCallBack',
    callback: message.callback,
    data: {
      isSuccess: 1
    }
  },
  '*'
);

type 与调用类型的对应关系：

| SDK 调用 | 回调 type | | -------------------------- | ------------- | | requestApi、requestApp | receiveData | | permissions | permissions | | 其他带回调的 API | IMCallBack |

H5 宿主需要在父级 window 上注入：

window['h5-app-version'] = '宿主版本号';

跨域 iframe 无法读取父页面字段时，SDK 会按 H5 容器处理。SDK 只接收 event.source === window.parent 的标准浏览器消息；source === null 的回包会被拒绝，网页宿主应通过 IMSDK.web.createHost 绑定真实 iframe WindowProxy。

回调生命周期

回调被调用后会立即从全局回调表中删除。
requestApi 回调在 30 秒后仍未收到响应时会被清理。
其他 API 回调在 10 分钟后仍未收到响应时会被清理。
当前清理行为不会主动调用 Web 侧回调，也不会生成超时错误。

H5 容器外的行为

SDK 面向 App WebView 和宿主 iframe。在普通浏览器顶层页面中，如果不存在原生桥且未注入 h5-app-version，调用不会发送给宿主；传入回调时，SDK 会以 undefined 调用该回调。

导出的类型与工具

除默认导出的 IMSDK 外，包还导出：

类型与枚举：MessageTypeEnum、IMSDKConfig、IMPaymentParams、IMNavigateParams、IMRequestParams、IMRequestAppParams、IMPopupParams、IMShareParams、IMSystemShareParams、IMDownLoadParams、IMBehaviorCaptchaParams、IMVibrateParams、IMChainCurrencyEnum 等。
工具：safeJSONParse、uuidv4、getOS、Md5。

大整数 JSON 解析示例：

import { safeJSONParse } from 'im2-link-jssdk';

const data = safeJSONParse('[123456789123456789123456789, 2.3]');
// 超出 JavaScript 安全整数范围的数字以字符串形式保留

本地开发

npm install
npm run build
npm run doc

npm run build：生成 ESM、CommonJS 和类型声明到 dist/。
npm run doc：根据源码类型和注释生成 TypeDoc 到 docs/。
项目要求 Node.js >= 22.0.0。

发布流程见 PUBLISH.md。

网页宿主接口 `web`

网页容器可以直接使用 IMSDK.web.createHost（也可 import { web }），不需要创建游戏端 SDK 实例或传入 app token。该入口没有自动监听副作用，也不会改动 iOS/Android/PC 的原生桥。

import IMSDK from 'im2-link-jssdk';

const host = IMSDK.web.createHost({
  getTarget: () => iframe.contentWindow ? {
    source: iframe.contentWindow,
    origin: new URL(iframe.src).origin,
    key: `${currentAccountId}:${currentAppId}:${iframe.src}`
  } : null,
  onMessage: async (request) => {
    if (request.message.type !== 'share') return;
    // params 为 { type: 'cardGame', param: { show_type, game_path, ... } }。
    // 宿主必须校验 message.appid 与当前 iframe 的可信应用资料，然后让用户选会话。
    const accepted = await selectAndShare(request.message.params, request.signal);
    request.reply('IMCallBack', { isSuccess: accepted ? 1 : 0 });
  }
});
host.listen();
// iframe 关闭/重新加载、切账号和卸载时：
host.stop();

getTarget 必须来自宿主 iframe，不得用收到的 event.origin 或消息里的 appid 生成信任规则。origin 必须精确匹配，禁止 *。显式绑定 origin: 'null' 才接受 opaque iframe，此时回包使用浏览器要求的 *，仍严格绑定 WindowProxy。
key 标识当前应用/账号/页面。异步工作前使用 request.isCurrent()；重新加载同一地址时也应 stop() 后 listen()，中止旧业务。监听只校验窗口来源，不代替宿主的 app token/权限验证。
reply('IMCallBack' | 'receiveData' | 'permissions', data) 自动带上原 callback，只能回复一次。停止或目标变化后的回复返回 false。业务回调 share(params, cb) 继续收到 boolean，不改变旧 API。
onMessage 的 Promise 拒绝时回 {isSuccess:0,error:'HOST_ERROR'}；可用 onError 接入宿主诊断，不应输出完整请求凭据。不支持的业务应由宿主明确回失败。
默认只分发 SDK 已声明消息类型，额外旧游戏事件通过 additionalMessageTypes 注册；normalizeMessage 只用于拆开宿主已有扩展包装，执行前已经校验 source/origin。
已有事件循环可调用 handleMessage(event)；不要同时再把同一事件交给自己的业务处理器。web.parseMessage(value) 只做对象/JSON 结构解析，不做来源或权限验证。
同源与跨域 iframe 都支持网页通信，不要求父网页注入 h5-app-version。原生环境仍优先现有原生桥。没有原生桥、没有标记的顶层独立页仍不冒充宿主。

H5 游戏分享宿主将 isSuccess:1 定义为用户确认后，所有选中目标均被 IM 发送 API 接受；这不代表送达/已读。取消、忙碌、不可用及部分失败回 0，原始响应附带 status/sent/failed。iOS 现有分享没有实现结果回包，不应把“已弹出选择器”写为它的成功合同。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

im2-link-jssdk

在线文档

目录

安装

快速开始

H5 小程序要求

API 概览

平台信息

支付

返回、会话与导航

返回

打开会话

宿主导航

权限

打开小程序

状态栏与原生弹框

设置状态栏颜色

拉起原生弹框

网络请求与 App 数据交互

由宿主发起网络请求

与宿主交换业务数据

WebView 布局与方向

调整输入框高度

切换横屏

分享

短视频分享

棋牌游戏分享

系统分享

下载

行为验证码

系统振动

宿主接入协议

Web 回调语义

Web 发给宿主的统一消息

各平台发送通道

原生宿主返回回调

H5 容器返回回调

回调生命周期

H5 容器外的行为

导出的类型与工具

本地开发

网页宿主接口 web

网页宿主接口 `web`