新手指南

1.应用背景

为满足分行和商户实现个性化和本地化的场景和需求,在确保客户和系统信息安全的前提下,将手机银行客户端、主机(服务)端、招乎的部分接口和信息开放给各分行(或可信任的第三方开发者)使用。分行同事可在此接口的基础上快速开发自己的应用,也就是所谓的小程序。在开发小程序的过程中,一般都会涉及到小程序和客户端之间的数据交互,而此文档主要用于描述客户端向小程序开发者开发的接口及其使用方法。


2.什么是JS-SDK

1.什么是JS-SDK

JS-SDK是招行手机银行App对H5页面开放的原生功能调用接口。它允许前端通过特定Js方法,直接调用App客户端的定位、分享、扫码、NFC等Native功能。JS-SDK,H5页面和Native功能之间的关系如下图所示。



接口主要分为如下几大类:

基础
界面
路由
媒体
分享
设备
位置
其他

2.JS-SDK接口形式

基于历史版本迭代原因,目前手机银行App主要存在两种JS-SDK接口形式:

  • cmblapi
    7.3.0版本开始陆续新增了一些cmblapi接口,相比于原来旧cmbls接口调用更加简单方便(后续新增接口一般以cmblapi接口形式提供)。

  • cmbls
    7.3.0版本以前,页面和Native功能之间主要通过cmbls接口来交互(注:7.3.0及其以后版本仍然兼容存量的cmbls接口)。


3.JS-SDK调用方式

部分功能同时存在cmblapi和cmbls两种接口,这两种接口的调用方式不同,请参考总览内相应篇章的调用说明。


3.什么是CMBLS接口

3.1 小程序和App交互过程

通过以上描述可知小程序和App交互主要包含两个方面:

(1)  调用客户端服务程序

小程序通过调用cmblsJSExecutor函数来调用客户端服务程序(例如,获取当前的位置或者读取手机通讯录等)。cmblsCommand为对应的命令。命令格式如下所示:

http://CMBLS/cmd?id=xxx & arg1=‍yyy ‍&‍‍‍ arg2=zzz...

其中:

cmblscmd:CMBLS命令,例如gps,addressbook等。

id:表示命令调用标识,可由商户自定义,无位数限制

argx:表示该命令的其他参数


(2)  获取客户端返回结果

小程序通过调用回调函数来获取客户端返回的结果。

(1) 成功回调函数

CMBLS.xxx.successCallback(id, message)

(2) 失败回调函数

CMBLS.xxx.failCallback(id, message)

其中

xxx:表示对应的CMBLS命令,如gps,addressbook等。

id:和cmblsCommand的id字段相同,标识命令。

message:App返回结果。


3.2 调用示例

使用CMBLS接口的过程就是发送CMBLS命令并获取结果的过程,以GPS接口为例,该程序的主要功能是调用客户端的GPS定位服务,并获取当前位置的经纬度等位置信息。

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "_http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>CMBLS调用示例</title>
</head>
<body>
<script type="text/javascript" language="javascript">
function cmblsJSExecutor(cmblsCommand)
{
    if (window.cmblsExecutor) {
        var cmblsExecutor = window.cmblsExecutor || {};
        window.cmblsExecutor.executeCmbls("1.0", cmblsCommand);
    } else {
        document.addEventListener('CMBLSExecutorReady', function () {
            var cmblsExecutor = window.cmblsExecutor || {};
            window.cmblsExecutor.executeCmbls("1.0", cmblsCommand);
        }, false);
    }
};
CMBLS = CMBLS || {};
CMBLS.gps = {};
CMBLS.gps.successCallback = function(id, message)
{
    alert("CMBLS gps调用成功,id:"+ id + ",message: "+message);
};
CMBLS.gps.failCallback = function(id, message)
{
    alert("CMBLS gps调用失败,id:"+ id + ",message: "+message);
};
</script>
<br/>
<div style="color:red">
 <br>
    <button style="color:red" onclick="cmblsJSExecutor('http://CMBLS/gps?id=123')">执行cmbls调用命令: "http://CMBLS/gps?id=123"</button>
</br>
</div>
</body>
</html>




4.如何使用CMBLS接口

3.1 小程序和App交互过程

通过以上描述可知小程序和App交互主要包含两个方面:

(1)  调用客户端服务程序

小程序通过调用cmblsJSExecutor函数来调用客户端服务程序(例如,获取当前的位置或者读取手机通讯录等)。cmblsCommand为对应的命令。命令格式如下所示:

http://CMBLS/cmd?id=xxx & arg1=‍yyy ‍&‍‍‍ arg2=zzz...

其中:

cmblscmd:CMBLS命令,例如gps,addressbook等。

id:表示命令调用标识,可由商户自定义,无位数限制

argx:表示该命令的其他参数


(2)  获取客户端返回结果

小程序通过调用回调函数来获取客户端返回的结果。

(1) 成功回调函数

CMBLS.xxx.successCallback(id, message)

(2) 失败回调函数

CMBLS.xxx.failCallback(id, message)

其中

xxx:表示对应的CMBLS命令,如gps,addressbook等。

id:和cmblsCommand的id字段相同,标识命令。

message:App返回结果。


3.2 调用示例

使用CMBLS接口的过程就是发送CMBLS命令并获取结果的过程,以GPS接口为例,该程序的主要功能是调用客户端的GPS定位服务,并获取当前位置的经纬度等位置信息。

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "_http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>CMBLS调用示例</title>
</head>
<body>
<script type="text/javascript" language="javascript">
function cmblsJSExecutor(cmblsCommand)
{
    if (window.cmblsExecutor) {
        var cmblsExecutor = window.cmblsExecutor || {};
        window.cmblsExecutor.executeCmbls("1.0", cmblsCommand);
    } else {
        document.addEventListener('CMBLSExecutorReady', function () {
            var cmblsExecutor = window.cmblsExecutor || {};
            window.cmblsExecutor.executeCmbls("1.0", cmblsCommand);
        }, false);
    }
};
CMBLS = CMBLS || {};
CMBLS.gps = {};
CMBLS.gps.successCallback = function(id, message)
{
    alert("CMBLS gps调用成功,id:"+ id + ",message: "+message);
};
CMBLS.gps.failCallback = function(id, message)
{
    alert("CMBLS gps调用失败,id:"+ id + ",message: "+message);
};
</script>
<br/>
<div style="color:red">
 <br>
    <button style="color:red" onclick="cmblsJSExecutor('http://CMBLS/gps?id=123')">执行cmbls调用命令: "http://CMBLS/gps?id=123"</button>
</br>
</div>
</body>
</html>




5.如何快速构建CMBLS接口调用程序?

通过上面的例子,可以了解如何调用gps接口,那么如何快速构建其他的的CMBLS接口调用程序呢?结合上面的demo,修改步骤如下:

4.1 修改cmblsCommand

也就是cmblsJSExecutor函数的参数,将cmblsCommand替换为对应的CMBLS接口命令即可,具体的CMBLS接口命令参见对应的章节。以调用通讯录接口为例,只需将将 'http://CMBLS/gps?id=123'替换为 http://cmbls/addressbook?id=XXX即可。


4.2 修改回调函数

将回调函数部分改为对应接口的回调函数,同样以通讯录接口为例,可以将上面GPS回调函数的部分改为


CMBLS = CMBLS || {};

CMBLS.addressbook= {};

CMBLS.addressbook.successCallback = function(id, message)

{

       alert("CMBLS addressbook调用成功,id:"+ id + ",message: "+message);

};

CMBLS.addressbook.failCallback = function(id, message)

{

       alert("CMBLS addressbook调用失败,id:"+ id + ",message: "+message);

};


6.cmblapi调用方法(新)

本篇介绍的调用方法只适用于cmblapi类型的接口,请参考以下步骤和示例代码来调用(请注意版本适配,cmblapi接口是从App 7.3.0或更高的版本才陆续开始支持,低于7.3.0以下版本均不支持调用

一、调用方法

1.下载Js文件

请开发者下载如下地址的js进行开发

稳定版

名称更新时间下载地址更新内容
cmblapi_7.3.0_min_20190409161736.js20190409下载

手机银行App小组将不定期更新相关js文件,文件中末尾数字代表更新时间,越大代表越新。默认新版js都将兼容旧版js

2.引用Js文件

如果使用了AMD/CMD规范,可在 module 中使用 require() 引入模块:

  1. var cmblapi = require('path/to/cmblapi_7300.js');

如果使用了AMD/CMD规范,可直接在Html中引入Js Bridge模块,建议直接在<head>中引入:

  1. <head>

  2. <script src="path/to/cmblapi_7300.js"></script>

  3. </head>


3.调用cmblapi接口

业务场景中直接调用cmblapi对象的相应接口,通用调用格式如下所示(代码中apiName、key字段替换为相应接口定义名称):

  1. cmblapi.apiName({

  2.   key1:value1,

  3.   key2:value2,

  4. ......

  5.   success:function(res){

  6. //code for success result

  7. },

  8.   fail:function(res){

  9. // code for fail result

  10. }

  11. })


4.其他说明

需要注意的是由于js bridge的机制问题,无法保证在iframe内正常调用JSAPI,请避免在iframe内使用


二、完整代码示例

以调用GPS定位接口为例

  1. cmblapi.getLocation({

  2.  type:'bd',//使用百度定位

  3.  success:function(res){

  4.     console.log(res);

  5. }

  6.  fail:function(res){

  7.     console.log(res);

  8. }

  9. })


7.用户拒绝授权后该如何处理

如果要求必须通过接口调用客户端信息才能使用服务的,可在页面上提示用户“如果不授权提供地理位置等信息,将无法使用XX服务,是否重新授权?”后,调用敏感信息接口授权提示接口发起授权请求。请注意,如果客户仍然拒绝授权,切勿多次反复调用授权接口,避免流程陷入死循环及影响用户体验。