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ō)明：關于(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ō)明

具體處理

接入方獲取當前的(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ō)明

具體處理

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ō)明

具體處理

登錄成功:

//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ō)明

具體處理

請求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ō)明

method 參數的(de)合法值

dataType 參數的(de)合法值

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

responseType 參數的(de)合法值

encrypted 參數的(de)合法值

cipherFlag 參數的(de)合法值

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

success 回調參數:

fail 回調參數：

那麽轉發請求的(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ō)明：小程序SDK對外提供生命周期的(de)兩個(gè)回調。分别是(shì)開始加載和(hé / huò)關閉。 分别對應着回調中的(de)miniPageOnStart方法和(hé / huò)miniPageOnDestroy方法

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

回調中的(de)miniPageOnStart方法

方法含義

public void miniPageOnStart(String appId)

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

參數說(shuō)明

具體處理

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

回調中miniPageOnDestroy方法

方法含義

public void miniPageOnDestroy(String appId)

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

參數說(shuō)明

具體處理

可以(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();