Android 小程序 SDK 集成流程

集成準備

獲取SDK

請聯系工作人(rén)員獲取小程序對應的(de)Android版本的(de)SDK

開始集成

本文檔适用于(yú)Android Studio工具

導入SDK

加入AAR

解壓SDK壓縮包,将aar 放入工程主module的(de)libs目錄下。

修改配置

在(zài)項目主module的(de)build.gradle中添加依賴。

SDK接入

初始化

方法含義

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

SDK的(de)初始化和(hé / huò)回調。

參數說(shuō)明:

屬性 類型 說(shuō)明 是(shì)否爲(wéi / wèi)空
activity Activity activity對象 不(bù)能爲(wéi / wèi)空
miniAppIdAlias String 小程序識别碼 不(bù)能爲(wéi / wèi)空
iMiniAppCallback IMiniAppCallback SDK提供給接入方的(de)接口回調 不(bù)能爲(wéi / wèi)空

說(shuō)明:關于(yú)線程的(de)問題說(shuō)明
接入方調用SDK提供的(de)方法,都需要(yào / yāo)在(zài)UI線程。
SDK提供的(de)回調都在(zài)UI線程。

具體處理

詳細的(de)處理細節,請參考SDK提供的(de)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) {
    }
});

下面對回調中出(chū)現的(de)方法依次進行詳細的(de)說(shuō)明

自定義小程序頂部導航欄樣式

初始化配置類MiniAppInitConfig

概要(yào / yāo)介紹

小程序初始化配置類MiniAppInitConfig, 可通過Builder構建者模式創建,提供的(de)功能如下。

1、自定義小程序頂部導航欄樣式 (如:設置導航欄高度)

2、設置小程序默認Icon

3、設置小程序加載頁GIF圖片

自定義頂部導航欄樣式 API

API - navigationBarBackgroundColor

設置頂部導航欄背景顔色。默認顔色值爲(wéi / wèi)#3b3f42

接口定義

public Builder navigationBarBackgroundColor(int color)
				

參數說(shuō)明

  • color:顔色值,爲(wéi / wèi)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)
				

參數說(shuō)明

  • unit:尺寸單位,如px、dp等,通過原生類android.util.TypedValue可設置不(bù)同的(de)高度單位,如設置dp則爲(wéi / wèi)TypedValue.COMPLEX_UNIT_DIP
  • navigationBarHeight:高度值大(dà)小, 爲(wéi / wèi)Int類型,單位爲(wéi / wèi)第一(yī / yì /yí)個(gè)參數unit的(de)值,高度值必須大(dà)于(yú)0,否則顯示高度爲(wéi / wèi)默認值大(dà)小

示例代碼

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

API - navigationBarTitleName

設置頂部導航欄标題名稱。該Title名稱也(yě)可通過jsbridge調用SDK相關API進行動态設置,若H5界面動态設置該Title名稱,則此處設置将被覆蓋

接口定義

public Builder navigationBarTitleName(String titleName)
				

參數說(shuō)明

  • titleName:标題名, 爲(wéi / wèi)String字符串類型

示例代碼

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

API - navigationBarTitleTextColor

設置頂部導航欄标題字體顔色。默認顔色值爲(wéi / wèi)#FFFFFF

接口定義

public Builder navigationBarTitleTextColor(int color)
				

參數說(shuō)明

  • color:顔色值,爲(wéi / wèi)Int類型,注意:非資源ID, resource ID可通過getResources().getColor(R.color.xxx)函數轉化

示例代碼

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

API - navigationBarTitleTextSize

設置頂部導航欄标題字體大(dà)小。默認值爲(wéi / wèi)18sp

接口定義

public Builder navigationBarTitleTextSize(int unit,float textSize)
				

參數說(shuō)明

  • unit:尺寸單位,如px、dp等,通過原生類android.util.TypedValue可設置不(bù)同的(de)高度單位,如設置dp則爲(wéi / wèi)TypedValue.COMPLEX_UNIT_DIP
  • textSize:文字字體大(dà)小,值爲(wéi / wèi)float類型,傳入的(de)值必須大(dà)于(yú)0,否則顯示爲(wéi / wèi)默認字體大(dà)小18sp

示例代碼

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

API - navigationBarMoreImage

設置頂部導航欄右側 “更多” 按鈕圖片,默認爲(wéi / wèi)". . .",三個(gè)白色小點按鈕。

接口定義

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

參數說(shuō)明

  • 三個(gè)重載函數,分别支持以(yǐ)resourceId、以(yǐ)drawable對象、以(yǐ)bitmap對象的(de)形式設置,開發者調用其中一(yī / yì /yí)種方式設置即可

示例代碼

以(yǐ)resourceId的(de)方式設置爲(wéi / wèi)例

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

API - navigationBarCloseImage

設置頂部導航欄右側 “關閉” 按鈕圖片,默認爲(wéi / wèi)"X"型圖片

接口定義

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

參數說(shuō)明

  • 三個(gè)重載函數,分别支持以(yǐ)resourceId、以(yǐ)drawable對象、以(yǐ)bitmap對象的(de)形式設置,開發者調用其中一(yī / yì /yí)種方式設置即可

示例代碼

以(yǐ)resourceId的(de)方式設置爲(wéi / wèi)例

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

設置小程序默認Icon API

API - miniAppDefaultIcon

設置小程序默認Icon,用于(yú)在(zài)"關于(yú)小程序"頁面,當網絡加載小程序Icon出(chū)錯時(shí)顯示

接口定義

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

參數說(shuō)明

  • 三個(gè)重載函數,分别支持以(yǐ)resourceId、以(yǐ)drawable對象、以(yǐ)bitmap對象的(de)形式設置,開發者調用其中一(yī / yì /yí)種方式設置即可

示例代碼

以(yǐ)resourceId的(de)方式設置爲(wéi / wèi)例

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

設置小程序加載頁gif圖片 API

API - setLoadingGifImage

設置小程序加載頁gif圖片,網絡加載HTML未成功前,将顯示加載頁,提醒用戶正在(zài)加載,不(bù)自定義gif圖片,則使用SDK默認的(de)gif圖片

接口定義

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

參數說(shuō)明

  • resourceId: gif圖片的(de)資源id,若隻想改變圖片寬高,使用SDK默認gif資源,resourceId值則填入MiniAppInitConfig.DEFAULT_LOADING_RESOURCES即可
  • widthUnit:尺寸單位,如px、dp等,通過原生類android.util.TypedValue可設置不(bù)同的(de)寬度單位,如設置dp則爲(wéi / wèi)TypedValue.COMPLEX_UNIT_DIP
  • heightUnit:尺寸單位,如px、dp等,通過原生類android.util.TypedValue可設置不(bù)同的(de)高度單位,如設置dp則爲(wéi / wèi)TypedValue.COMPLEX_UNIT_DIP
  • imageWidth: 設置gif圖片的(de)寬度, 爲(wéi / wèi)Int類型,單位取決于(yú)widthUnit的(de)值
  • imageHeight: 設置gif圖片的(de)高度,爲(wéi / wèi)Int類型,單位取決于(yú)imageHeight的(de)值

示例代碼

以(yǐ)dp爲(wéi / wèi)尺寸單位設置爲(wéi / wèi)例

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對象,或者個(gè)别配置未設置,則會使用SDK内默認配置

獲取小程序配置信息

說(shuō)明:SDK請求接入方從網絡上(shàng)獲取當前小程序的(de)配置信息,接入方請求完畢後,将返回數據告知SDK
這(zhè)個(gè)在(zài)回調中的(de) setMiniAppConfig方法中觸發。

下面對setMiniAppConfig方法進行詳細說(shuō)明:

public void setMiniAppConfig(String localMiniAppVersion, IMiniAppConfigCallback configCallback)
				

方法含義

SDK請求接入方從網絡上(shàng)獲取當前小程序的(de)配置信息,接入方請求完畢後,将返回數據告知SDK(包括成功,失敗)

參數說(shuō)明

屬性 類型 說(shuō)明
localMiniAppVersion String 本地(dì / de)數據庫中當前小程序的(de)版本,用于(yú)網絡請求中請求版本參數
configCallback IMiniAppConfigCallback SDK提供給接入方的(de)設置配置數據的(de)接口引用

具體處理

接入方獲取當前的(de)小程序配置信息 請求參數有兩個(gè)
1. code:當前小程序的(de)識别碼
2. version:當前小程序的(de)版本,值爲(wéi / wèi)回調中的(de)參數localMiniAppVersion.
具體網絡接口的(de)詳細說(shuō)明,請查看 小程序服務端文檔

當配置接口請求完成後,進行如下的(de)轉換,将請求結果告知SDK

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

下載小程序離線包

說(shuō)明:SDK通知接入方下載離線包,并将下載後的(de)結果告知SDK
在(zài)回調中的(de) setOfflinePackagePath方法中觸發

下面對setOfflinePackagePath方法進行詳細說(shuō)明: 1.方法含義

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

SDK通知接入方下載離線包,并将下載後的(de)結果告知SDK

參數說(shuō)明

屬性 類型 說(shuō)明
appId String 小程序id
fullDownloadUrl String 小程序全量離線包下載地(dì / de)址url
offlinePackageStorageDirectory String 下載完成後離線包的(de)存儲目錄
offlinePackageName String 下載後離線包需要(yào / yāo)重命名的(de)名字
downloadCallback IMiniAppOfflinePackageDownloadCallback SDK提供給接入方的(de)下載完成接口引用

具體處理

1.接入方使用fullDownloadUrl進行離線包下載
2.下載成功後,将離線包重新命名爲(wéi / wèi) offlinePackageName,将其保存在(zài)offlinePackageStorageDirectory這(zhè)個(gè)路徑下
3.下載成功調用 downloadCallback.setOfflinePackagePath(offlinePackagePath+"/"+offlinePackageName);方法
4.下載失敗後調用 downloadCallback.downloadError(errorMsg),其中errorMsg爲(wéi / wèi)下載失敗的(de)原因

小程序請求登錄

說(shuō)明:SDK請求接入方進行登錄,然後将結果告訴SDK
這(zhè)個(gè)會在(zài)回調中的(de) requestLogin方法中觸發。

下面對requestLogin方法進行詳細說(shuō)明 方法含義

public void requestLogin(String appId, IMiniAppLoginCallback loginCallback)
				

SDK請求接入方進行登錄,然後将結果告訴SDK

參數說(shuō)明

屬性 類型 說(shuō)明
appId String 小程序id
loginCallback IMiniAppLoginCallback SDK提供給接入方的(de)登錄完成後回調的(de)接口引用

具體處理

登錄成功:

//1.登錄後服務端返回的(de)數據(爲(wéi / wèi)Json格式的(de)字符串)
String responseSuccessJsonString = "{}";

//2.将Json格式的(de)字符串轉換爲(wéi / wèi)Map
Map mapSuccess = new Gson().fromJson(responseSuccessJsonString, Map.class);

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

登錄失敗

//1.登錄後服務端返回的(de)數據,爲(wéi / wèi)Json格式的(de)字符串
String responseErrorJsonString = "{}";

//2.将Json格式的(de)字符串轉換爲(wéi / wèi)Map
Map mapError = new Gson().fromJson(responseErrorJsonString, Map.class);

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

小程序請求接口轉發

說(shuō)明:小程序内網絡請求的(de)轉發,請進行網絡請求,并将結果告訴SDK
這(zhè)個(gè)在(zài)回調中的(de) requestNetWork方法中觸發。

方法含義

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

小程序内網絡請求的(de)轉發,請進行網絡請求,并将結果告訴SDK

參數說(shuō)明

屬性 類型 說(shuō)明
appId String 小程序id
accessName String 拼接URL時(shí)使用
forwardCallback IMiniAppNetWorkForwardCallback SDK提供給接入方的(de)接口轉發完成後回調的(de)接口引用

具體處理

請求URL的(de)完整格式爲(wéi / wèi):

String wholeUrl = host + accessName + api;
				

例如: 轉發接口的(de) host如下:

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

請求轉發的(de)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的(de)格式參數說(shuō)明

forwardInfoJsonString爲(wéi / wèi)一(yī / yì /yí)個(gè)Json格式的(de)字符串. 例如:

{
  "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"
}

字段含義說(shuō)明

屬性 類型 默認值 必填 說(shuō)明 最低版本
url string 是(shì) 開發者服務器接口地(dì / de)址  
data string/object 請求的(de)參數  
method string POST HTTP 請求方法  
dataType string json 返回的(de)數據格式  
responseType string text 響應的(de)數據類型  
encrypted boolean/string false 是(shì)否加密  
cipherFlag string 加密方式  

method 參數的(de)合法值

說(shuō)明 最低版本
GET HTTP 請求 GET  
POST HTTP 請求 POST  

dataType 參數的(de)合法值

小程序sdk不(bù)用關心,前端處理

說(shuō)明 最低版本
json 返回的(de)數據爲(wéi / wèi) JSON,返回後會對返回的(de)數據進行一(yī / yì /yí)次 JSON.parse  
其他(tā) 不(bù)對返回的(de)内容進行 JSON.parse  

responseType 參數的(de)合法值

說(shuō)明 最低版本
text 響應的(de)數據爲(wéi / wèi)文本  

encrypted 參數的(de)合法值

說(shuō)明 最低版本
false或者空 不(bù)加密  
true 加密  

cipherFlag 參數的(de)合法值

encrypted爲(wéi / wèi)false或空時(shí)不(bù)傳該字段

說(shuō)明 最低版本
002 登陸後交易使用的(de)加密  
005 登陸前交易使用的(de)加密  

success 回調參數:

屬性 類型 說(shuō)明 最低版本
data string/Object/Arraybuffer 開發者服務器返回的(de)數據  
statusCode number 開發者服務器返回的(de) HTTP 狀态碼  
header Object 開發者服務器返回的(de) HTTP Response Header  

fail 回調參數:

屬性 類型 說(shuō)明 最低版本
error Object 開發者服務器返回的(de)錯誤信息,包括code錯誤碼, msg錯誤信息字段  

那麽轉發請求的(de)完整的(de)URL如下:

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

小程序錯誤回調

說(shuō)明:小程序SDK統一(yī / yì /yí)的(de)錯誤回調,包括接入方傳入的(de)參數不(bù)合法,包括SDK内部的(de)異常. 這(zhè)個(gè)在(zài)回調中的(de) miniAppError方法中觸發

下面對miniAppError方法進行詳細說(shuō)明: 方法含義

小程序SDK統一(yī / yì /yí)的(de)錯誤回調,包括接入方傳入的(de)參數不(bù)合法,包括SDK内部的(de)異常

參數說(shuō)明

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

error_code:錯誤碼 error_msg:錯誤信息

具體處理

//可以(yǐ)使用Toast,方便調試和(hé / huò)錯誤調試
				 Toast.makeText(MainActivity.this, error_code + ":" + error_msg, Toast.LENGTH_LONG).show();

錯誤碼說(shuō)明

錯誤碼 說(shuō)明
100 配置接口傳遞的(de)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 不(bù)是(shì)一(yī / yì /yí)個(gè)數字
111 小程序配置Json中 accessName is empty
112 小程序配置Json中 miniAppIdAlias is empty
200 當前SDK不(bù)支持該小程序,請升級SDK版本
201 客戶端獲取Config信息失敗
300 客戶端下載離線包失敗
301 客戶端傳遞的(de)小程序離線包存儲地(dì / de)址爲(wéi / wèi)空
302 小程序離線包不(bù)存在(zài)
303 小程序離線包,壓縮文件md5值和(hé / huò)配置接口中返回的(de)不(bù)一(yī / yì /yí)緻
304 小程序解壓目錄中沒有文件
305 小程序解壓失敗
306 解壓文件中包含非法字符
400 加載的(de)文件中出(chū)現了(le/liǎo)sha1不(bù)一(yī / yì /yí)緻的(de)情況

小程序生命周期

說(shuō)明:小程序SDK對外提供生命周期的(de)兩個(gè)回調。分别是(shì)開始加載和(hé / huò)關閉。 分别對應着回調中的(de) miniPageOnStart方法和(hé / huò)miniPageOnDestroy方法

下面分别對這(zhè)兩個(gè)方法進行詳細的(de)說(shuō)明

回調中的(de)miniPageOnStart方法

方法含義

public void miniPageOnStart(String appId)
				

小程序界面開始加載的(de)回調.

參數說(shuō)明

屬性 類型 說(shuō)明
appId String 小程序id

具體處理

可以(yǐ)根據自己的(de)業務,進行統計等等處理.

回調中miniPageOnDestroy方法

方法含義

public void miniPageOnDestroy(String appId)
				

小程序界面關閉的(de)回調.

參數說(shuō)明

屬性 類型 說(shuō)明
appId String 小程序id

具體處理

可以(yǐ)根據自己的(de)業務,進行統計等等處理.

小程序日志控制

SDK提供了(le/liǎo)Log日志開關的(de)方法MiniAppLog.setDebug()

SDK内部的(de)日志,默認是(shì)開着的(de),建議在(zài)release模式下關閉日志。

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

小程序版本

SDK提供獲取當前的(de)版本号,方便調試。

  MiniAppSDK.getInstance().getSDKVersionName();