Android 小程序 SDK 集成流程

集成准备

获取SDK

请联系工作人员获取小程序对应的Android版本的SDK

开始集成

本文档适用于Android Studio工具

导入SDK

加入AAR

解压SDK压缩包,将aar 放入工程主module的libs目录下。

修改配置

在项目主module的build.gradle中添加依赖。

SDK接入

初始化

方法含义

MiniAppSDK.getInstance().init(activity, miniAppIdAlias, iMiniAppCallback);

SDK的初始化和回调。

参数说明:

属性 类型 说明 是否为空
activity Activity activity对象 不能为空
miniAppIdAlias String 小程序识别码 不能为空
iMiniAppCallback IMiniAppCallback SDK提供给接入方的接口回调 不能为空

说明:关于线程的问题说明
接入方调用SDK提供的方法,都需要在UI线程。
SDK提供的回调都在UI线程。

具体处理

详细的处理细节,请参考SDK提供的Sample工程。

MiniAppSDK.getInstance().init(SampleActivity.this, miniAppIdAlias, new IMiniAppCallback() {
    @Override
    public MiniAppInitConfig getMiniAppInitConfig() {
        return null;
    }

    @Override
    public boolean checkMiniAppSslCertification(SslCertificate sslCertificate, String url) {
        return true;
    }

    @Override
    public void setMiniAppConfig(String localMiniAppVersion, IMiniAppConfigCallback configCallback) {
    }

    @Override
    public void setOfflinePackagePath(String appId, String fullDownloadUrl, String offlinePackagePath, IMiniAppOfflinePackageDownloadCallback downloadCallback) {
    }

    @Override
    public void requestLogin(String appId, IMiniAppLoginCallback iMiniProgramLoginCallback) {
    }

    @Override
    public void requestNetWork(final String appId, final String accessName, final String forwardInfo, final IMiniAppNetWorkForwardCallback iMiniProgramNetWorkForwardCallback) {
    }

    @Override
    public void miniAppError(int error_code, String error_msg) {
    }

    @Override
    public void miniPageOnStart(String appId) {
    }

    @Override
    public void miniPageOnDestroy(String appId) {
    }
});

下面对回调中出现的方法依次进行详细的说明

自定义小程序顶部导航栏样式

初始化配置类MiniAppInitConfig

概要介绍

小程序初始化配置类MiniAppInitConfig, 可通过Builder构建者模式创建,提供的功能如下。

1、自定义小程序顶部导航栏样式 (如:设置导航栏高度)

2、设置小程序默认Icon

3、设置小程序加载页GIF图片

自定义顶部导航栏样式 API

API - navigationBarBackgroundColor

设置顶部导航栏背景颜色。默认颜色值为#3b3f42

接口定义

public Builder navigationBarBackgroundColor(int color)
				

参数说明

  • color:颜色值,为Int类型,注意:非资源ID, resource ID可通过getResources().getColor(R.color.xxx)函数转化

示例代码

MiniAppInitConfig config = new MiniAppInitConfig.Builder()
                        .navigationBarBackgroundColor(color)
                        .build();

API - navigationBarHeight

设置顶部导航栏高度。默认值46dp

接口定义

public Builder navigationBarHeight(int unit,int navigationBarHeight)
				

参数说明

  • unit:尺寸单位,如px、dp等,通过原生类android.util.TypedValue可设置不同的高度单位,如设置dp则为TypedValue.COMPLEX_UNIT_DIP
  • navigationBarHeight:高度值大小, 为Int类型,单位为第一个参数unit的值,高度值必须大于0,否则显示高度为默认值大小

示例代码

MiniAppInitConfig config = new MiniAppInitConfig.Builder()
                        .navigationBarHeight(TypedValue.COMPLEX_UNIT_DIP,46)
                        .build();

API - navigationBarTitleName

设置顶部导航栏标题名称。该Title名称也可通过jsbridge调用SDK相关API进行动态设置,若H5界面动态设置该Title名称,则此处设置将被覆盖

接口定义

public Builder navigationBarTitleName(String titleName)
				

参数说明

  • titleName:标题名, 为String字符串类型

示例代码

MiniAppInitConfig config = new MiniAppInitConfig.Builder()
                        .navigationBarTitleName(titleName)
                        .build();

API - navigationBarTitleTextColor

设置顶部导航栏标题字体颜色。默认颜色值为#FFFFFF

接口定义

public Builder navigationBarTitleTextColor(int color)
				

参数说明

  • color:颜色值,为Int类型,注意:非资源ID, resource ID可通过getResources().getColor(R.color.xxx)函数转化

示例代码

MiniAppInitConfig config = new MiniAppInitConfig.Builder()
                        .navigationBarTitleTextColor(color)
                        .build();

API - navigationBarTitleTextSize

设置顶部导航栏标题字体大小。默认值为18sp

接口定义

public Builder navigationBarTitleTextSize(int unit,float textSize)
				

参数说明

  • unit:尺寸单位,如px、dp等,通过原生类android.util.TypedValue可设置不同的高度单位,如设置dp则为TypedValue.COMPLEX_UNIT_DIP
  • textSize:文字字体大小,值为float类型,传入的值必须大于0,否则显示为默认字体大小18sp

示例代码

MiniAppInitConfig config = new MiniAppInitConfig.Builder()
                        .navigationBarTitleTextSize(TypedValue.COMPLEX_UNIT_SP,18)
                        .build();

API - navigationBarMoreImage

设置顶部导航栏右侧 “更多” 按钮图片,默认为". . .",三个白色小点按钮。

接口定义

public Builder navigationBarMoreImage(int resourceId)
    public Builder navigationBarMoreImage(Drawable drawable)
    public Builder navigationBarMoreImage(Bitmap bitmap)

参数说明

  • 三个重载函数,分别支持以resourceId、以drawable对象、以bitmap对象的形式设置,开发者调用其中一种方式设置即可

示例代码

以resourceId的方式设置为例

MiniAppInitConfig config = new MiniAppInitConfig.Builder()
                        .navigationBarMoreImage(R.drawable.xxx)
                        .build();

API - navigationBarCloseImage

设置顶部导航栏右侧 “关闭” 按钮图片,默认为"X"型图片

接口定义

public Builder navigationBarCloseImage(int resourceId)
    public Builder navigationBarCloseImage(Drawable drawable)
    public Builder navigationBarCloseImage(Bitmap bitmap)

参数说明

  • 三个重载函数,分别支持以resourceId、以drawable对象、以bitmap对象的形式设置,开发者调用其中一种方式设置即可

示例代码

以resourceId的方式设置为例

MiniAppInitConfig config = new MiniAppInitConfig.Builder()
                        .navigationBarCloseImage(R.drawable.xxx)
                        .build();

设置小程序默认Icon API

API - miniAppDefaultIcon

设置小程序默认Icon,用于在"关于小程序"页面,当网络加载小程序Icon出错时显示

接口定义

public Builder miniAppDefaultIcon(int resourceId)
    public Builder miniAppDefaultIcon(Drawable drawable)
    public Builder miniAppDefaultIcon(Bitmap bitmap)

参数说明

  • 三个重载函数,分别支持以resourceId、以drawable对象、以bitmap对象的形式设置,开发者调用其中一种方式设置即可

示例代码

以resourceId的方式设置为例

MiniAppInitConfig config = new MiniAppInitConfig.Builder()
                        .miniAppDefaultIcon(R.drawable.xxx)
                        .build();

设置小程序加载页gif图片 API

API - setLoadingGifImage

设置小程序加载页gif图片,网络加载HTML未成功前,将显示加载页,提醒用户正在加载,不自定义gif图片,则使用SDK默认的gif图片

接口定义

Builder setLoadingGifImage( int resourceId, int widthUnit, int heightUnit, int imageWidth, int imageHeight)
				

参数说明

  • resourceId: gif图片的资源id,若只想改变图片宽高,使用SDK默认gif资源,resourceId值则填入MiniAppInitConfig.DEFAULT_LOADING_RESOURCES即可
  • widthUnit:尺寸单位,如px、dp等,通过原生类android.util.TypedValue可设置不同的宽度单位,如设置dp则为TypedValue.COMPLEX_UNIT_DIP
  • heightUnit:尺寸单位,如px、dp等,通过原生类android.util.TypedValue可设置不同的高度单位,如设置dp则为TypedValue.COMPLEX_UNIT_DIP
  • imageWidth: 设置gif图片的宽度, 为Int类型,单位取决于widthUnit的值
  • imageHeight: 设置gif图片的高度,为Int类型,单位取决于imageHeight的值

示例代码

以dp为尺寸单位设置为例

MiniAppInitConfig config = new MiniAppInitConfig.Builder()
                        .setLoadingGifImage(R.drawable.xxx,
                                            TypedValue.COMPLEX_UNIT_DIP,
                                            TypedValue.COMPLEX_UNIT_DIP,
                                            60,60)
                        .build();

创建MiniAppInitConfig对象示例代码

 MiniAppInitConfig config = new MiniAppInitConfig.Builder()
                        .navigationBarBackgroundColor(color)
                        .navigationBarHeight(TypedValue.COMPLEX_UNIT_DIP,46)
                        .navigationBarTitleName("XX小程序")
                        .navigationBarTitleTextColor(color)
                        .navigationBarTitleTextSize(TypedValue.COMPLEX_UNIT_SP,18)
                        .navigationBarMoreImage(R.drawable.xxx)
                        .setLoadingGifImage(MiniAppInitConfig.DEFAULT_LOADING_RESOURCES,
                                            TypedValue.COMPLEX_UNIT_DIP,
                                            TypedValue.COMPLEX_UNIT_DIP,60,60)
                        .miniAppDefaultIcon(R.drawable.xxx)
                        .build();

注意:若未初始化该Config对象,或者个别配置未设置,则会使用SDK内默认配置

获取小程序配置信息

说明:SDK请求接入方从网络上获取当前小程序的配置信息,接入方请求完毕后,将返回数据告知SDK
这个在回调中的 setMiniAppConfig方法中触发。

下面对setMiniAppConfig方法进行详细说明:

public void setMiniAppConfig(String localMiniAppVersion, IMiniAppConfigCallback configCallback)
				

方法含义

SDK请求接入方从网络上获取当前小程序的配置信息,接入方请求完毕后,将返回数据告知SDK(包括成功,失败)

参数说明

属性 类型 说明
localMiniAppVersion String 本地数据库中当前小程序的版本,用于网络请求中请求版本参数
configCallback IMiniAppConfigCallback SDK提供给接入方的设置配置数据的接口引用

具体处理

接入方获取当前的小程序配置信息 请求参数有两个
1. code:当前小程序的识别码
2. version:当前小程序的版本,值为回调中的参数localMiniAppVersion.
具体网络接口的详细说明,请查看 小程序服务端文档

当配置接口请求完成后,进行如下的转换,将请求结果告知SDK

  //response:配置接口请求返回的Json格式的数据
  String responseJsonString = "{...}";
  Map configMap = new Gson().fromJson(responseJsonString, Map.class);
  configCallback.setMiniAppConfigJsonString(map);

下载小程序离线包

说明:SDK通知接入方下载离线包,并将下载后的结果告知SDK
在回调中的 setOfflinePackagePath方法中触发

下面对setOfflinePackagePath方法进行详细说明: 1.方法含义

public void setOfflinePackagePath(String appId, String fullDownloadUrl, String offlinePackageStorageDirectory, String offlinePackageName, IMiniAppOfflinePackageDownloadCallback downloadCallback)
				

SDK通知接入方下载离线包,并将下载后的结果告知SDK

参数说明

属性 类型 说明
appId String 小程序id
fullDownloadUrl String 小程序全量离线包下载地址url
offlinePackageStorageDirectory String 下载完成后离线包的存储目录
offlinePackageName String 下载后离线包需要重命名的名字
downloadCallback IMiniAppOfflinePackageDownloadCallback SDK提供给接入方的下载完成接口引用

具体处理

1.接入方使用fullDownloadUrl进行离线包下载
2.下载成功后,将离线包重新命名为 offlinePackageName,将其保存在offlinePackageStorageDirectory这个路径下
3.下载成功调用 downloadCallback.setOfflinePackagePath(offlinePackagePath+"/"+offlinePackageName);方法
4.下载失败后调用 downloadCallback.downloadError(errorMsg),其中errorMsg为下载失败的原因

小程序请求登录

说明:SDK请求接入方进行登录,然后将结果告诉SDK
这个会在回调中的 requestLogin方法中触发。

下面对requestLogin方法进行详细说明 方法含义

public void requestLogin(String appId, IMiniAppLoginCallback loginCallback)
				

SDK请求接入方进行登录,然后将结果告诉SDK

参数说明

属性 类型 说明
appId String 小程序id
loginCallback IMiniAppLoginCallback SDK提供给接入方的登录完成后回调的接口引用

具体处理

登录成功:

//1.登录后服务端返回的数据(为Json格式的字符串)
String responseSuccessJsonString = "{}";

//2.将Json格式的字符串转换为Map
Map mapSuccess = new Gson().fromJson(responseSuccessJsonString, Map.class);

//3.调用loginCallback.setLoginSuccess()方法
loginCallback.setLoginSuccess(mapSuccess);

登录失败

//1.登录后服务端返回的数据,为Json格式的字符串
String responseErrorJsonString = "{}";

//2.将Json格式的字符串转换为Map
Map mapError = new Gson().fromJson(responseErrorJsonString, Map.class);

//3.调用loginCallback.setLoginError()方法
loginCallback.setLoginError(mapError);

小程序请求接口转发

说明:小程序内网络请求的转发,请进行网络请求,并将结果告诉SDK
这个在回调中的 requestNetWork方法中触发。

方法含义

public void requestNetWork(String appId, String accessName, String forwardInfoJsonString, IMiniAppNetWorkForwardCallback forwardCallback)
				

小程序内网络请求的转发,请进行网络请求,并将结果告诉SDK

参数说明

属性 类型 说明
appId String 小程序id
accessName String 拼接URL时使用
forwardCallback IMiniAppNetWorkForwardCallback SDK提供给接入方的接口转发完成后回调的接口引用

具体处理

请求URL的完整格式为:

String wholeUrl = host + accessName + api;
				

例如: 转发接口的 host如下:

String host = "http://197.3.156.92:41302";
				

请求转发的forwardInfoJsonString字段值如下:

{
  "method": "POST",
  "dataType": "json",
  "responseType": "text",
  "encrypted": false,
  "header": {
    "content-type": "application/x-www-form-urlencoded"
  },
  "data": {},
  "api": "/initQueryBuilding?_origin=cmbc&t=Mon%20Jun%2024%202019%2015%3A54%3A44%20GMT%2B0800%20%28CST%29&rowCount=10"
}

forwardInfoJsonString的格式参数说明

forwardInfoJsonString为一个Json格式的字符串. 例如:

{
  "method": "POST",
  "dataType": "json",
  "responseType": "text",
  "encrypted": false,
  "header": {
    "content-type": "application/x-www-form-urlencoded"
  },
  "data": {},
  "api": "/initQueryBuilding?_origin=cmbc&t=Mon%20Jun%2024%202019%2015%3A54%3A44%20GMT%2B0800%20%28CST%29&rowCount=10"
}

字段含义说明

属性 类型 默认值 必填 说明 最低版本
url string 开发者服务器接口地址  
data string/object 请求的参数  
method string POST HTTP 请求方法  
dataType string json 返回的数据格式  
responseType string text 响应的数据类型  
encrypted boolean/string false 是否加密  
cipherFlag string 加密方式  

method 参数的合法值

说明 最低版本
GET HTTP 请求 GET  
POST HTTP 请求 POST  

dataType 参数的合法值

小程序sdk不用关心,前端处理

说明 最低版本
json 返回的数据为 JSON,返回后会对返回的数据进行一次 JSON.parse  
其他 不对返回的内容进行 JSON.parse  

responseType 参数的合法值

说明 最低版本
text 响应的数据为文本  

encrypted 参数的合法值

说明 最低版本
false或者空 不加密  
true 加密  

cipherFlag 参数的合法值

encrypted为false或空时不传该字段

说明 最低版本
002 登陆后交易使用的加密  
005 登陆前交易使用的加密  

success 回调参数:

属性 类型 说明 最低版本
data string/Object/Arraybuffer 开发者服务器返回的数据  
statusCode number 开发者服务器返回的 HTTP 状态码  
header Object 开发者服务器返回的 HTTP Response Header  

fail 回调参数:

属性 类型 说明 最低版本
error Object 开发者服务器返回的错误信息,包括code错误码, msg错误信息字段  

那么转发请求的完整的URL如下:

JSONObject forwardInfoJsonObject = new JSONObject(forwardInfoJsonString);
String api = forwardInfoJsonObject.optString("api");
String wholeUrl = host + accessName + api;

小程序错误回调

说明:小程序SDK统一的错误回调,包括接入方传入的参数不合法,包括SDK内部的异常. 这个在回调中的 miniAppError方法中触发

下面对miniAppError方法进行详细说明: 方法含义

小程序SDK统一的错误回调,包括接入方传入的参数不合法,包括SDK内部的异常

参数说明

public void miniAppError(final int error_code, final String error_msg)
				

error_code:错误码 error_msg:错误信息

具体处理

//可以使用Toast,方便调试和错误调试
				 Toast.makeText(MainActivity.this, error_code + ":" + error_msg, Toast.LENGTH_LONG).show();

错误码说明

错误码 说明
100 配置接口传递的map==null
101 配置接口返回数据错误
102 配置接口返回Json数据异常! response==null
103 小程序配置Json中 miniAppId is empty
104 小程序配置Json中 miniAppVersion is empty
105 小程序配置Json中 fullDownloadUrl is empty
106 小程序配置Json中 fullMd5 is empty
107 小程序配置Json中 loadType is empty
108 小程序配置Json中 urlPrefix is empty
109 小程序配置Json中 sdkMinVer is empty
110 小程序配置Json中 sdkMinVer 不是一个数字
111 小程序配置Json中 accessName is empty
112 小程序配置Json中 miniAppIdAlias is empty
200 当前SDK不支持该小程序,请升级SDK版本
201 客户端获取Config信息失败
300 客户端下载离线包失败
301 客户端传递的小程序离线包存储地址为空
302 小程序离线包不存在
303 小程序离线包,压缩文件md5值和配置接口中返回的不一致
304 小程序解压目录中没有文件
305 小程序解压失败
306 解压文件中包含非法字符
400 加载的文件中出现了sha1不一致的情况

小程序生命周期

说明:小程序SDK对外提供生命周期的两个回调。分别是开始加载和关闭。 分别对应着回调中的 miniPageOnStart方法和miniPageOnDestroy方法

下面分别对这两个方法进行详细的说明

回调中的miniPageOnStart方法

方法含义

public void miniPageOnStart(String appId)
				

小程序界面开始加载的回调.

参数说明

属性 类型 说明
appId String 小程序id

具体处理

可以根据自己的业务,进行统计等等处理.

回调中miniPageOnDestroy方法

方法含义

public void miniPageOnDestroy(String appId)
				

小程序界面关闭的回调.

参数说明

属性 类型 说明
appId String 小程序id

具体处理

可以根据自己的业务,进行统计等等处理.

小程序日志控制

SDK提供了Log日志开关的方法MiniAppLog.setDebug()

SDK内部的日志,默认是开着的,建议在release模式下关闭日志。

  if (!BuildConfig.DEBUG){
      MiniAppLog.setDebug(false);
  }

小程序版本

SDK提供获取当前的版本号,方便调试。

  MiniAppSDK.getInstance().getSDKVersionName();