商户通服务号接入网页开发文档

版本：V1.1.0

日期：20220110

一、安装

npm i sht-sdk

也可通过以下标签引入的方式：

<script src="https://mopen.unionpay.com/scripts/sht.js"></script>

二、使用方法

如果通过npm方法安装，使用时需要import，如下：

import * as sht from "sht-sdk"

然后就可调用方法了，如sht.config(successFunc, failFunc, args);

如果使用标签引入的方式安装，直接调用sht.config(successFunc, failFunc, args);

商户通jsbridge规范定义了前端H5页面和商户通客户端之间通讯的规则，通讯的主要过程包括以下三个过程：

1.认证过程：该过程是向商户通app提供您的身份信息进行权限认证，具体的参数见注册接口的使用示例，每个url需要调到一次；(该过程为必须过程）

2.检测过程：该过程是检测商户通App版本支持的接口，具体调用见检测接口的使用示例；（该过程非必须，如果需要使用特殊权限接口建议使用）

3.使用功能性接口：认证成功之后调用的的功能性接口，具体使用见功能接口的使用示例；（该过程按需使用即可）

4.使用UI接口：认证成功之后调用的的UI接口，具体使用见UI接口的使用示例；（该过程按需使用即可）

1、注册接口

接口说明：js调用native认证过程，具体参数目前如下:

config(success, fail, args); 

参数说明

参数名|是否必须|参数类型|说明 ---|---|---|--- success|是|function|成功的回调函数 fail|是|function|失败的回调函数 args|是|object|调用接口的传参，封装为对象

使用示例

sht.config(function(successData){}, function(failData){}, {
    debug: true, // 开启调试模式（默认是false，关闭）,开启之后调用所有api的返回值会在客户端alert出来
    appId: '', // 必填，公众号的唯一标识
    timestamp: '', // 必填，生成签名的时间戳
    nonceStr: '', // 必填，生成签名的随机串
    signature: '',// 必填，签名
    jsApiList: [] // 必填，需要使用的JS接口列表
}); 

签名生成规则如下：参与签名的字段包括nonceStr（随机字符串）, 有效的jsApiTicket, timestamp（时间戳）, url（当前网页的URL，不包含#及其后面部分） 。对所有待签名参数按照字段名的ASCII 码从小到大排序（字典序）后，使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串string1。对string1作sha256加密，字段名和字段值都采用原始值，不进行URL 转义。返回数据规范:

successData {
    "resultCode": "000000", 
    "resultMsg" : "成功",
}
failData {
    "resultCode": "响应码", 
    "resultMsg": "描述",
}

2、检测接口，检测客户端app版本是否支持某api接口

checkApi(success, fail, args);

参数说明：

参数名|是否必须|参数类型|说明 ---|---|---|--- success|是|function|成功的回调函数 fail|是|function|失败的回调函数 args|是|object|需要检测的接口，以对象形式发送，{"jsApiList":['takePhoto']}

使用示例：

sht.checkApi(function(successData){}, function(failData){}, {
    "jsApiList":['takePhoto', 'getLocation']
    });

返回数据规范：

successData {
    "resultCode":"000000",
    "resultMsg" : "success",
    "data": {
        "takePhoto":true,
        "getLocation":false
    }
}

failData {
    "resultCode":"响应码"，
    "resultMsg":"描述",
}

3、功能性接口

3.1、扫码功能（包括二维码和条形码）

scanQRCode(success, fail, args);  

参数说明：

参数名|是否必须|参数类型|说明 ---|---|---|--- success|是|function|成功的回调函数 fail|是|function|失败的回调函数 args|否|object|将所有参数放入对象

使用示例：

sht.scanQRCode(function(successData){}, function(failData){});

返回数据规范：

successData {
    "resultCode":"000000",
    "resultMsg" : "success",
    "data": "https://www.baidu.com"
}

failData {
    "resultCode":"响应码"，
    "resultMsg":"描述",
}

3.2、检测NFC硬件功能

checkNFC(success, fail, args);

参数说明：

参数名|是否必须|参数类型|说明 ---|---|---|--- success|是|function|成功的回调函数 fail|是|function|失败的回调函数 args|否|object|将所有参数放入对象

使用示例：

sht.checkNFC(function(successData){}, function(failData){});

返回数据规范：

successData {
    "resultCode":"000000",
    "resultMsg" : "描述",
}

failData {
    "resultCode":"响应码"，
    "resultMsg":"描述",
}

3.3、创建NFC标签

createNFCTag(success, fail, args);

参数说明：

参数名|是否必须|参数类型|说明 ---|---|---|--- success|是|function|成功的回调函数 fail|是|function|失败的回调函数 args|是|object|将所有参数放入对象

使用示例：

sht.createNFCTag(function(successData){}, function(failData){}, {"data":"sht"});

返回数据规范：

successData {
    "resultCode":"000000",
    "resultMsg" : "描述",
}

failData {
    "resultCode":"响应码"，
    "resultMsg":"描述",
}

3.4、定位功能

getLocation(success, fail, args);

参数说明：

参数名|是否必须|参数类型|说明 ---|---|---|--- success|是|function|成功的回调函数 fail|是|function|失败的回调函数 args|否|object|将所有参数放入对象

使用示例：

sht.getLocation(function(successData){}, function(failData){});

返回数据规范：

successData {
    "resultCode":"000000",
    "resultMsg" : "描述",
    "data":{
        "longitude":17.012,
        "latitude": 65.011,
        "speed":100,
        "accuracy":0.15
    }
}

failData {
    "resultCode":"响应码"，
    "resultMsg":"描述",
}

3.5、拍照或者选取照片功能

takePhoto(success, fail, args);

参数说明：

参数名|是否必须|参数类型|说明 ---|---|---|--- success|是|function|成功的回调函数 fail|是|function|失败的回调函数 args|否|object|可选，{type："photo"}只能选图片，{type:"camera"}只能拍照，不传时相机和图片都可以，其他值调用失败回调。

使用示例：

sht.takePhoto(function(successData){}, function(failData){});

返回数据规范：

successData {
    "resultCode":"000000",
    "resultMsg" : "描述",
    "data":{
        "size":844084,
        "type":"image/jpeg",
        "content":"fdsafdsafdsafdsafsadfdsafdsafdsafdsafdsafdsafd"， //图片的base64编码
        "mode":"2"
    }
}

failData {
    "resultCode":"响应码"，
    "resultMsg":"描述",
}

3.6、外部用户获取授权接口

getAuthCode(success, fail, args);

参数说明：

参数名|是否必须|参数类型|说明 ---|---|---|--- success|是|function|成功的回调函数 fail|是|function|失败的回调函数 args|是|object|需要发送的数据信息，以对象形式发送例如：{appId:"服务号ID",scope:"base 或 userInfo"}

使用示例：

sht.getAuthCode(success, fail, {appId:"服务号ID",scope:"base 或 userInfo"});

返回数据规范：

successData {
    "data":{
        "code":"..."
    },
    "resultCode":"000000",
    "resultMsg":"成功"
}

failData {
    "data":{
        "status":"1",
        "msg":"服务号不存在"
    }
    "resultCode":"010001",
    "resultMsg":"拉取授权信息失败"
}

3.7、获取银行卡列表和默认卡接口

getBankCard(success, fail, args)

参数说明：

参数名|是否必须|参数类型|说明 ---|---|---|--- success|是|function|成功的回调函数 fail|是|function|失败的回调函数 args|是|object|是否弹出银行卡列表，参数isPopList，true代表弹出卡列表，由用户选择一张卡返回；false代表默认返回一张银行卡信息

使用示例：

sht.getBankCard(success, fail, {isPopList:false});

返回数据规范：

successData {
    "data":{
        "cardNoSuffix":"8935",
        "issuerName":"农业银行",
        "token":"...",
        "cardNoPrefix":"6200",
    },
    "resultCode":"000000",
    "resultMsg":"成功"
}

failData {
    "resultCode":"009002",
    "resultMsg":"无银行卡"
}

3.8、扫描银行卡接口

scanBankCard(success, fail)

参数说明：

参数名|是否必须|参数类型|说明 ---|---|---|--- success|是|function|成功的回调函数 fail|是|function|失败的回调函数，扫描不成功会一直扫描，不会调用失败函数，但是为了保持一致，需要传入失败回调，可传入空函数

使用示例：

sht.scanBankCard(success, fail);

返回数据规范：

successData {
    "data":"6214 1234 5678 6852",
    "resultCode":"000000",
    "resultMsg":"成功"
}

3.9、扫描身份证接口

scanIDCard(success, fail)

参数说明：

参数名|是否必须|参数类型|说明 ---|---|---|--- success|是|function|成功的回调函数 fail|是|function|失败的回调函数

使用示例：

sht.scanIDCard(success, fail);

返回数据规范：

successData {
    "data":{
        "err_msg":"",
        "err_no":"0",
        "brithday":"19780405",
        "sex":"男",
        "idNum":"340223197804051234",
        "nationality":"汉",
        "address":"安徽省芜湖市...",
        "name":"张山",
        "base64ImageData":"..."
    },
    "resultCode":"000000",
    "resultMsg":"成功"
}

failData {
    "resultCode":"009002",
    "resultMsg":"扫描身份证失败"
}

3.10、扫描营业执照接口

scanLicense(success, fail)

参数说明：

参数名|是否必须|参数类型|说明 ---|---|---|--- success|是|function|成功的回调函数 fail|是|function|失败的回调函数

使用示例：

sht.scanLicense(success, fail);

返回数据规范：

successData {
    "resultCode": "000000",
    "resultMsg": "成功",
    "data": {
        "scc": "无",
        "err_msg": "",
        "address": "北京市朝阳区师家攻村156号1层06号记机关",
        "err_no": "0",
        "validity": "长期",
        "registerDate": "无",
        "name": "北京树托育型务有限公司",
        "corporator": "州",
        "number": "无",
        "format": "json",
        "type": "其他有阻任公到",
        "registerCapital": "10053万元"
    }
}

failData {
    "resultCode":"013001",
    "resultMsg":"识别失败，确认照片"
}

3.11、分享接口

sharePlugin(success, fail, args)

参数说明：

参数名|是否必须|参数类型|说明 ---|---|---|--- success|是|function|成功的回调函数 fail|是|function|失败的回调函数 args|是|object|包含：type（必输），data（必输）

args分一下场景

(1)链接分享

{
    type: "01"
    data: {title:"标题示例", "url":"https://www.baidu.com","img":"baseUrl"}
}

(2)图片分享

{
    type: "02"
    data: {"img" : "baseUrl"}
}

(3)截屏分享

{
    type: "03"
    data: {}
}

使用示例：

sht.sharePlugin(success, fail, {type:"01", data:{title:"标题", url:"www.baidu.com", img:"baseUrl"}});

返回数据规范：

successData {
    "resultCode": "000000",
    "resultMsg": "成功",
}

failData {
    "resultCode":"014001",
    "resultMsg":"分享失败"
}

3.12、调起第三方地图导航接口

callNav(success, fail, args)

参数说明：

参数名|是否必须|参数类型|说明 ---|---|---|--- success|是|function|成功的回调函数 fail|是|function|失败的回调函数 args|是|object|包含：type（必输），data（必输）

args示例:

{
  "type" : "invoke",         //必填，选择操作，”check“：检测；”invoke“：调用
  "data" : {
      "dlat": "31.242214",    //必填，目的地纬度
      "dlon": "121.672465",   //必填，目的地经度
      "dname": "上丰路1483弄",    //选填，目的地名称
      "coordtype": "gcj02",    //必填，原始坐标系类型，bd09ll（百度经纬度坐标）gcj02（经国测局加密的坐标）wgs84（gps获取的原始坐标）
      "target" : "baidu"      //必填，要调起的地图类型，”gaode“、”baidu“、”apple“三选一
      }
}

使用场景：

(1)type为check，检测本地安装APP列表：

sht.callNav(success, fail, {
  "type" : "check",  
  "data" : {}
});

返回数据规范：

successData {
    "resultCode": "000000",
    "resultMsg": "成功"
    "data": {

​     	"list" : ["gaode","baidu","apple"]

​    }
}

failData {
​        "resultCode":"000005",
​        "resultMsg":"H5传递过来的参数非法"

}

(2)type为invoke，唤起第三方地图APP

sht.callNav(success, fail, {
  "type" : "invoke",  
  "data" : {     
      "dlat": "31.242214",    
      "dlon": "121.672465",  
      "dname": "上丰路1483弄",    
      "coordtype": "gcj02",
      "target" : "baidu" 
      }
});

返回数据规范（此种情况下没有成功回调，只有错误回调）：

failData {
​        "resultCode":"000005",
​        "resultMsg":"H5传递过来的参数非法"

}

failData {
        "resultCode":"015001",
        "resultMsg":"本地未安装指定地图"

}

4.1、打开新webview接口

sht.startNewWebview(url, closeCallback)

参数说明：

参数名|是否必须|参数类型|说明 ---|---|---|--- url|是|String|页面地址 closeCallback|否|function|新webview关闭时的回调函数

4.2、关闭当前webview接口

sht.closeWebview()

参数说明：

无

##全量响应码参考：

响应码|描述 ---|--- 000000|成功 000001|客户端异常 000002|api接口列表未配置 000003|当前客户端不支持该接口 000004|服务器异常 000005|参数不合法 000006|域名验证失败 000007|请求错误 000008|服务器验证失败 001001|签名验证不通过 001002|接口调用越权 003001|扫码失败 004001|设备支持nfc，但是未开启 004002|设备不支持nfc 005001|没有发现tag标签 005002|标签不可写 005003|tag写数据错误 005004|tag镜像操作错误 005005|tag锁定错误 005006|手机与tag在写入过程中断开连接 006001|客户端定位未开启 006002|定位失败 006003|该服务号未授权定位 008001|通讯错误 009001|授权失败 009002|扫描身份证失败 //需要修改为012001 010001|拉取授权信息失败 011001|获取银行卡失败 011002|无银行卡 013001|识别失败，确认照片 013002|网络或者客户端内部错误 015001|本地未安装指定地图 014001|分享失败 014002|资源解析错误