Webstart SDK

web JS插件&Demo，通过定义一套通信协议及机制，实现web与本地程序之间的HTTP双向通信。

How to install

For JQuery and original JS

Download js lib from npmjs

npm i webstart-sdk

add js to html

<script type="text/javascript" src="/webstart-sdk.min.js"></script>

For TypeScript such as Angular Vue React

Install

npm i webstart-sdk

Import

import * as WebStartSdk from 'webstart-sdk';

协议规范

• 通过HTTP通信，通信端口：36666，36667，36668。为防止端口冲突，定义三个端口，只要有一个端口正常，即锁定为该端口。
• HTTP协议：为最大化浏览器兼容性，所有请求都使用GET请求。
• 通信发起方：所有的通信都为单向通信，由浏览器发起请求。

协议API

|No.|URL|名称|接口类型|备注| |---|------|------|------|------| |1.|/health|健康检查接口|自动|一旦启动就一直轮询，检查本地客户端程序是否状态正常| |2.|/exec|命令执行接口|手动|由浏览器端发起，向本地客户端程序发送命令| |3.|/push|客户端推送接口|自动|自动执行，当health接口中检测到有新的数据推送后自动调用| |4.|/exit|退出通信模式接口|手动|告诉本地客户端停止通信模式|

1.健康检查接口

Req

t=时间戳毫秒数

Res

{
  "status":true, // 固定返回
  "data":0       // 当有数据推送到前端时返回大于0的数，否则返回0
}

2.命令执行接口

Req

// cmd为必传参数，bizData为业务数据
// 未拆分发送
?cmd=命令行&t=时间戳毫秒数&bizData=jsonString

// 拆分发送 uuid、i、reduce三个参数仅当自动拆分启动，并且超过最大限长时才会有
?cmd=命令行&t=时间戳毫秒数&bizData=jsonString&uuid=&i=&reduce=

Desc

自动拆分逻辑：

• 配置为自动拆分时，即init参数配置了maxUrlLength属性
• 当提交的参数长度过长，SDK会计算将发出的URL是否超过限制（URL Encode后的长度）
• 如果超过限制，则根据maxUrlLength，计算需要拆分几次发送
• 由于URL Encode和平均发送的原因，因此每次发出的数据会小于maxUrlLength中定义的长度
• 对于被拆分的数据，每次请求中的uuid为同一个值，reduce为拆分的条数，i为当前为第i段
• 后端收到不完整的数据不可以进行解析操作，必须收到全部数据后再进行逻辑处理
• 为快速发送所有请求，SDK不保证拆分的数据的顺序，仅能通过i来区分（即后端最后收到的数据不一定是i=reduce-1的那条）
• 每次拆分的数据都要有返回值，如果未接收全，需要返回"code":"_SKIP"，告诉SDK忽略回调。仅且仅有最后接收到的那条数据不需要该属性，SDK进行回调。

Res

{
  "status":true,   // 返回执行结果状态
  "data":null,     // 用来返回数据给页面
  "code":"_SKIP"   // 仅当拆分时
}

3.客户端推送接口

Req

无

Res

{
  "status":true,   // 返回结果状态
  "data":null      // 用来返回数据给页面
}

4.退出程序

未检测到客户端状态，点击Exit后，立即退出通信模式，不调用接口。检测到客户端状态正常时，点击Exit调用/exit接口，并持续检测客户端状态，直到检测到客户端停止服务后，更新状态为OFF，并退出通信模式。

Req

无

Res

{
  "status":true,   // 返回结果状态
  "data":null      // 用来返回数据给页面
}

SDK

初始化

WebStartSdk.init(eventHandler, config);

eventHandler(event)

全局的事件处理回调

• event.type：
  • log：全局日志
  • clientStatus：本地程序状态变化
  • result：执行全局结果
  • push：客户端主动推送
• event.message 消息
• event.data 数据
• event.status 状态码

  function eventHandler(event) {
    if (event.type === 'log') {
      // 日志
    } else if (event.type === 'clientStatus') {
      // 本地程序状态变化
      // event.status:(OFF,ON,INITIAL)
    } else if (event.type === 'result') {
      // 执行全局结果
    } else if (event.type === 'push') {
      // 客户端主动推送
    }
  }

config 启动配置

   {
      // 是否自动启动（针对JNLP方式启动的客户端）,当需要通过Web启动JAVA程序时，需要将autoStart配置为true,并指定jnlpUrl的地址
      autoStart: true, // Optional
      jnlpUrl: 'http://127.0.0.1:8081/webclient.jnlp', // Optional
      // 当命令执行接口数据超过最大限度（包含URL及固定参数，并进行URL转码后的长度）后，会自动进行拆分多包发送（需要后端支持拆分合并）
      // 由于存在URL转码，实际发送的数据长度会低于设置的长度
      maxUrlLength: 8000, // Optional since V0.2.0
      // health接口检查频率，默认1000毫秒
      heartBeatCheckRate: 1000, // Optional since V0.3.0
      // health接口超时时间，默认1000毫秒
      heartBeatCheckTimeout: 1000, // Optional since V0.3.0
      port: [36666, 36667, 36668], // Default port Optional since V0.3.0
      // 拆分多包发送时的分组大小
      groupSendSize: 100,  // Optional sence V0.3.2
      // 拆分多包发送时每个分组之间的发送时差(毫秒)
      groupSendDelay: 1000  // Optional sence V0.3.2
   }

发送命令

    var cmdId = WebStartSdk.exec('cmd001', {
      param1: '123',
      param2: '456'
    }, function (res) {
      log('同步返回值' + JSON.stringify(res));
    });
    if (cmdId !== null) {
      log('执行命令已发送:' + cmdId);
    } else {
      log('执行命令发送失败');
    }

退出程序

/**
 * 退出程序,向后台发送退出命令
 * @param force 是否强制前端退出通信模式，不传或为false时，前端会一直等待后端退出（Optional）
 */
WebStartSdk.exit(force);

退出通信模式

/**
 * 退出通信,不向后台发送退出命令,仅前端退出
 */
WebStartSdk.disconnect();

CHANGELOG

V0.3.7

• 恢复'babel-polyfill'引入，避免项已存在的项目出错

V0.3.6

• 删除'babel-polyfill'引入，避免项目引入sdk已本身已有此插件导致重复引用错误

V0.3.5

• Fix Bug:解决Health接口导致内存不断增加的问题

V0.3.4

• Fix Bug:在Push接口返回的数据不正确的情况下，Push接口不工作的问题

V0.3.3

• Fix BUG:Push接口只工作一次或不工作的问题

V0.3.2

• 初始化配置中增加自动拆分分组配置，解决数据量超大拆包过多时，后续请求无法发出的问题

V0.3.1

• 初始化配置中增加对Health接口检查频率和超时时间的配置
• 退出时增加强制退出功能
• 支持自定义端口号，应对同时运行不同分组应用
• API增加disconnect()方法，仅前端断开通信

V0.2.1

Fix BUG:当以HTTPS方式运行时，由于浏览器安全性限制，无法打开放在HTTP下的JNLP文件

V0.2.0

命令执行接口增加自动拆分功能，解决当get请求过大被浏览器或后端应用拦截的问题

v0.1.1

接口增加时间戳，解决部分IE浏览器缓存不更新的问题。

v0.1.0

修改退出逻辑，已建立通信的情况下，实现优雅关机。

v0.0.1

初始版本发布。