微包JS SDK 开发文档

webox.jssdk.v1

集成说明

使用方式

请将此script链接增加至项目中

<script src="https://static.5upay.com/webox/webox.jssdk.v1.js"></script>

同时需要加入以下两个资源

<script src="https://static.5upay.com/webox/jssdk/static/wasm-pack/ehking-crypto.js"></script>
<script src="https://static.5upay.com/webox/jssdk/static/wasm-pack/ehking-crypto-x509.js"></script>

或者js代码中初始化

window.webox.asyncInit().then(() =
    console.info('init success')
}).catch(() => {
    console.error('init failed')
});

初始化与预加载

/**
 * 初始化加载微包内部需要的Script链接,
 * 若已经加载过,则不会重复加载,直接返回成功回调
 */
window.webox.init().then(() => {
    /**
     * 为了保证用户资金安全,微包内部的加解密采用沙箱进行,
     * 为了提高用户体验,建议在用户进入页面时进行预加载,
     * 以便于后续业务的快速启动
     *
     * 加载完毕后将存在内存中
     */
    window.webox.preload({
        merchantId: '89xxx9596', // 商编Id
        walletId: '520000xxxxxxxxxx752', // 钱包ID
    });
});

业务唤起函数

window.webox.evoke({
    merchantId, //商编Id
    walletId, //钱包ID
    token, // 预下单接口返回的token
    businessCode, // 启动业务类型
    blankNotifyUrl: 'YOU_CURRENT_URL', // 预留空白html地址用于微包内部通知使用
    // 例如：跳转银联侧绑卡通知使用，采用iframe方式启动页面，
    // iframe中的一些事件会挂载到window对象中做为微包内部回调使用，
    // 为了避免与商户业务混淆，最好提供一个空白页面供微包内部使用
    portraitAuthCallbackUrl: 'YOU_CURRENT_URL/?token=${token}&merchantId=${merchantId}&walletId=${walletId}&businessCode=${businessCode}', // 用于人像认证回调地址
    //例: http://localhost:8889/?portraitAuthResult=success&token=00000&merchantId=89xxx9596&walletId=520000xxxxxxxxxx752&businessCode=ACCESS_CARDlIST
},
callback => { // 业务结果回调
    if(result){
        const code = result.businessCode;
        const status = result.status;
        const reason = result.reason;
        if(status == "SUCCESS"){
            // 业务成功
        } else if(status == "FAIL"){
            // 业务失败
        } else if(status == "CANCEL"){
            // 业务取消
        }
    }
});

配置设置

    window.webox.router = {
        enable: true, // 启用微包路由管理, 默认为false, 如果默认,则回退按钮会使浏览器回退上一页面
    }
    window.webox.controller = {
        // 设置顶部与底部安全区域, App包裹的H5页面请设置
        safeAreaInsets: {
            top: 20, // px
            bottom: 20, // px
        },
        userAgentSplit: '', // 如果你自定义了userAgent, 请设置此项, 用于微包内部分割userAgent获取应用名称与系统版本
        appName: '微包Demo', // 用于微包内部显示应用名称
    }

    // 微包样式配置
    window.webox.styleConfig({
        buttonBackground: 'green', // 按钮的背景颜色
        buttonColor: 'yellow', // 按钮的文字颜色
        lightButtonBorderColor: 'green', // 高亮按钮的边框颜色
        lightButtonColor: 'lightgreen', // 高亮按钮的文字颜色
        headBackground: 'green',// 标题头背景颜色
        headColor: 'yellow',// 标题头文字颜色
    });

微包跳转外部地址页面处理

const url = new URL(location.href);
window.webox.router = { // 此为微包配置,由集成方自行决定是否启用
    enable: true,
}
const portraitAuthResult = url.searchParams.get('portraitAuthResult');
const unionPayBindCardResult = url.searchParams.get('unionPayBindCardResult');
if (window.parent && window.parent.unionPayBindCardResult && unionPayBindCardResult) { // 银联绑卡回调判断
    window.parent.unionPayBindCardResult(unionPayBindCardResult);
} else if (portraitAuthResult && portraitAuthResult == 'success') { // 人像认证回调判断
    // document.getElementById('dialog').style = 'display: block' // 此处请看说明1
    function launchPortraitAuthResult(){
        const token = url.searchParams.get('token');
        const merchantId = url.searchParams.get('merchantId');
        const walletId = url.searchParams.get('walletId');
        const businessCode = url.searchParams.get('businessCode');
        selfEvoke(merchantId, walletId, token, businessCode, function (result) {
            showLoading(false);
            reqApiWithWalletQuery();
            if (result) {
            console.info(```{result.businessCode}, ``{result.status}, ${result.reason}`);
            }
        });
    }
    launchPortraitAuthResult(); // 若存在说明1的状况, 点击后执行此方法
}

微包在处理某些业务的情况下可能会启动外部地址跳转进行某些认证或其它业务相关操作,这就需要集成方在自己的页面中对此进行处理,以便于整个业务的畅通.

说明1:如果用户启动微包路由管理, 在部分浏览器存在保护策略的情况下,那么需要集成方在自身的页面中增加一个用户交互事件(例如弹窗),防止浏览器禁止路由,导致返回不正常的问题

微包配置

window.webox.router = {
    enable: true,
}

微包在浏览器中是否启用路由管理功能;ture启用/false关闭;

该功能指在微包业务页面中用户点击浏览器返回按钮可以正确返回上一个业务页面.

window.webox.styleConfig({
        buttonBackground: 'green', // 按钮的背景颜色
        buttonColor: 'yellow',  // 按钮的文字颜色
        lightButtonBorderColor: 'green', // 白色背景按钮的边框色
        lightButtonColor: 'lightgreen', // 白色背景按钮文字的颜色
        headBackground: 'green', // 标题头背景颜色
        headColor: 'yellow', // 标题头文字颜色
      });

微包样式配置; 可通过配置修改按钮与标题头区域的文字与背景的颜色;

微包业务枚举类型

window.webox.BusinessCode.RECHARGE; // 充值
window.webox.BusinessCode.TRANSFER; // 转账
window.webox.BusinessCode.WITHHOLDING; // 提现
window.webox.BusinessCode.REDPACKET; // 发红包
window.webox.BusinessCode.APP_PAY; //  订单支付
window.webox.BusinessCode.ACCESS_SAFETY; //安全设置
window.webox.BusinessCode.ACCESS_CARDlIST; // 绑卡管理

微包回调结果状态枚举类型

window.webox.EvokeResultStatus.SUCCESS;  // 业务操作成功
window.webox.EvokeResultStatus.FAIL; // 业务操作失败
window.webox.EvokeResultStatus.CANCEL;  // 业务被用户取消
window.webox.EvokeResultStatus.PROCESS;  // 业务操作进行中
window.webox.EvokeResultStatus.PORTRAIT_AUTH_FAILED; // 人像认证比对失败

业务说明

收银台业务

window.webox.BusinessCode.RECHARGE; // 充值
window.webox.BusinessCode.TRANSFER; // 转账
window.webox.BusinessCode.WITHHOLDING; // 提现
window.webox.BusinessCode.REDPACKET; // 发红包
window.webox.BusinessCode.APP_PAY; //  订单支付

此5种为收银台业务, 在业务回调结果result.status返回window.webox.EvokeResultStatus.SUCCESS 仅表示代码业务提交成功,仍需商户发起订单查询,确认订单状态

其它业务

window.webox.BusinessCode.ACCESS_SAFETY; //安全设置
window.webox.BusinessCode.ACCESS_CARDlIST; // 绑卡管理

在用户进入此业务页面会回调业务状态window.webox.EvokeResultStatus.SUCCESS, 说明业务页面进入成功;
在用户退出此业务页面会回调业务状态window.webox.EvokeResultStatus.CANCEL,说明用户已经离开此页面;