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