Android 小程序 SDK 集成流程
集成準(zhǔn)備
獲取SDK
請聯(lián)系工作人員獲取小程序?qū)?yīng)的Android版本的SDK
開始集成
本文檔適用于Android Studio工具
導(dǎo)入SDK
加入AAR
解壓SDK壓縮包,將aar 放入工程主module的libs目錄下。
修改配置
在項目主module的build.gradle中添加依賴。
SDK接入
初始化
方法含義
MiniAppSDK.getInstance().init(activity, miniAppIdAlias, iMiniAppCallback);
SDK的初始化和回調(diào)。
參數(shù)說明:
屬性 | 類型 | 說明 | 是否為空 |
---|---|---|---|
activity | Activity | activity對象 | 不能為空 |
miniAppIdAlias | String | 小程序識別碼 | 不能為空 |
iMiniAppCallback | IMiniAppCallback | SDK提供給接入方的接口回調(diào) | 不能為空 |
說明:關(guān)于線程的問題說明
接入方調(diào)用SDK提供的方法,都需要在UI線程。
SDK提供的回調(diào)都在UI線程。
具體處理
詳細(xì)的處理細(xì)節(jié),請參考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) {
}
});
下面對回調(diào)中出現(xiàn)的方法依次進(jìn)行詳細(xì)的說明
自定義小程序頂部導(dǎo)航欄樣式
初始化配置類MiniAppInitConfig
概要介紹
小程序初始化配置類MiniAppInitConfig, 可通過Builder構(gòu)建者模式創(chuàng)建,提供的功能如下。
1、自定義小程序頂部導(dǎo)航欄樣式 (如:設(shè)置導(dǎo)航欄高度)
2、設(shè)置小程序默認(rèn)Icon
3、設(shè)置小程序加載頁GIF圖片
自定義頂部導(dǎo)航欄樣式 API
API - navigationBarBackgroundColor
設(shè)置頂部導(dǎo)航欄背景顏色。默認(rèn)顏色值為#3b3f42
接口定義
public Builder navigationBarBackgroundColor(int color)
參數(shù)說明
- color:顏色值,為Int類型,注意:非資源ID, resource ID可通過getResources().getColor(R.color.xxx)函數(shù)轉(zhuǎn)化
示例代碼
MiniAppInitConfig config = new MiniAppInitConfig.Builder()
.navigationBarBackgroundColor(color)
.build();
API - navigationBarHeight
設(shè)置頂部導(dǎo)航欄高度。默認(rèn)值46dp
接口定義
public Builder navigationBarHeight(int unit,int navigationBarHeight)
參數(shù)說明
- unit:尺寸單位,如px、dp等,通過原生類android.util.TypedValue可設(shè)置不同的高度單位,如設(shè)置dp則為TypedValue.COMPLEX_UNIT_DIP
- navigationBarHeight:高度值大小, 為Int類型,單位為第一個參數(shù)unit的值,高度值必須大于0,否則顯示高度為默認(rèn)值大小
示例代碼
MiniAppInitConfig config = new MiniAppInitConfig.Builder()
.navigationBarHeight(TypedValue.COMPLEX_UNIT_DIP,46)
.build();
API - navigationBarTitleName
設(shè)置頂部導(dǎo)航欄標(biāo)題名稱。該Title名稱也可通過jsbridge調(diào)用SDK相關(guān)API進(jìn)行動態(tài)設(shè)置,若H5界面動態(tài)設(shè)置該Title名稱,則此處設(shè)置將被覆蓋
接口定義
public Builder navigationBarTitleName(String titleName)
參數(shù)說明
- titleName:標(biāo)題名, 為String字符串類型
示例代碼
MiniAppInitConfig config = new MiniAppInitConfig.Builder()
.navigationBarTitleName(titleName)
.build();
API - navigationBarTitleTextColor
設(shè)置頂部導(dǎo)航欄標(biāo)題字體顏色。默認(rèn)顏色值為#FFFFFF
接口定義
public Builder navigationBarTitleTextColor(int color)
參數(shù)說明
- color:顏色值,為Int類型,注意:非資源ID, resource ID可通過getResources().getColor(R.color.xxx)函數(shù)轉(zhuǎn)化
示例代碼
MiniAppInitConfig config = new MiniAppInitConfig.Builder()
.navigationBarTitleTextColor(color)
.build();
API - navigationBarTitleTextSize
設(shè)置頂部導(dǎo)航欄標(biāo)題字體大小。默認(rèn)值為18sp
接口定義
public Builder navigationBarTitleTextSize(int unit,float textSize)
參數(shù)說明
- unit:尺寸單位,如px、dp等,通過原生類android.util.TypedValue可設(shè)置不同的高度單位,如設(shè)置dp則為TypedValue.COMPLEX_UNIT_DIP
- textSize:文字字體大小,值為float類型,傳入的值必須大于0,否則顯示為默認(rèn)字體大小18sp
示例代碼
MiniAppInitConfig config = new MiniAppInitConfig.Builder()
.navigationBarTitleTextSize(TypedValue.COMPLEX_UNIT_SP,18)
.build();
API - navigationBarMoreImage
設(shè)置頂部導(dǎo)航欄右側(cè) “更多” 按鈕圖片,默認(rèn)為". . .",三個白色小點按鈕。
接口定義
public Builder navigationBarMoreImage(int resourceId)
public Builder navigationBarMoreImage(Drawable drawable)
public Builder navigationBarMoreImage(Bitmap bitmap)
參數(shù)說明
- 三個重載函數(shù),分別支持以resourceId、以drawable對象、以bitmap對象的形式設(shè)置,開發(fā)者調(diào)用其中一種方式設(shè)置即可
示例代碼
以resourceId的方式設(shè)置為例
MiniAppInitConfig config = new MiniAppInitConfig.Builder()
.navigationBarMoreImage(R.drawable.xxx)
.build();
API - navigationBarCloseImage
設(shè)置頂部導(dǎo)航欄右側(cè) “關(guān)閉” 按鈕圖片,默認(rèn)為"X"型圖片
接口定義
public Builder navigationBarCloseImage(int resourceId)
public Builder navigationBarCloseImage(Drawable drawable)
public Builder navigationBarCloseImage(Bitmap bitmap)
參數(shù)說明
- 三個重載函數(shù),分別支持以resourceId、以drawable對象、以bitmap對象的形式設(shè)置,開發(fā)者調(diào)用其中一種方式設(shè)置即可
示例代碼
以resourceId的方式設(shè)置為例
MiniAppInitConfig config = new MiniAppInitConfig.Builder()
.navigationBarCloseImage(R.drawable.xxx)
.build();
設(shè)置小程序默認(rèn)Icon API
API - miniAppDefaultIcon
設(shè)置小程序默認(rèn)Icon,用于在"關(guān)于小程序"頁面,當(dāng)網(wǎng)絡(luò)加載小程序Icon出錯時顯示
接口定義
public Builder miniAppDefaultIcon(int resourceId)
public Builder miniAppDefaultIcon(Drawable drawable)
public Builder miniAppDefaultIcon(Bitmap bitmap)
參數(shù)說明
- 三個重載函數(shù),分別支持以resourceId、以drawable對象、以bitmap對象的形式設(shè)置,開發(fā)者調(diào)用其中一種方式設(shè)置即可
示例代碼
以resourceId的方式設(shè)置為例
MiniAppInitConfig config = new MiniAppInitConfig.Builder()
.miniAppDefaultIcon(R.drawable.xxx)
.build();
設(shè)置小程序加載頁gif圖片 API
API - setLoadingGifImage
設(shè)置小程序加載頁gif圖片,網(wǎng)絡(luò)加載HTML未成功前,將顯示加載頁,提醒用戶正在加載,不自定義gif圖片,則使用SDK默認(rèn)的gif圖片
接口定義
Builder setLoadingGifImage( int resourceId, int widthUnit, int heightUnit, int imageWidth, int imageHeight)
參數(shù)說明
- resourceId: gif圖片的資源id,若只想改變圖片寬高,使用SDK默認(rèn)gif資源,resourceId值則填入MiniAppInitConfig.DEFAULT_LOADING_RESOURCES即可
- widthUnit:尺寸單位,如px、dp等,通過原生類android.util.TypedValue可設(shè)置不同的寬度單位,如設(shè)置dp則為TypedValue.COMPLEX_UNIT_DIP
- heightUnit:尺寸單位,如px、dp等,通過原生類android.util.TypedValue可設(shè)置不同的高度單位,如設(shè)置dp則為TypedValue.COMPLEX_UNIT_DIP
- imageWidth: 設(shè)置gif圖片的寬度, 為Int類型,單位取決于widthUnit的值
- imageHeight: 設(shè)置gif圖片的高度,為Int類型,單位取決于imageHeight的值
示例代碼
以dp為尺寸單位設(shè)置為例
MiniAppInitConfig config = new MiniAppInitConfig.Builder()
.setLoadingGifImage(R.drawable.xxx,
TypedValue.COMPLEX_UNIT_DIP,
TypedValue.COMPLEX_UNIT_DIP,
60,60)
.build();
創(chuàng)建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對象,或者個別配置未設(shè)置,則會使用SDK內(nèi)默認(rèn)配置
獲取小程序配置信息
說明:SDK請求接入方從網(wǎng)絡(luò)上獲取當(dāng)前小程序的配置信息,接入方請求完畢后,將返回數(shù)據(jù)告知SDK
這個在回調(diào)中的setMiniAppConfig
方法中觸發(fā)。
下面對setMiniAppConfig
方法進(jìn)行詳細(xì)說明:
public void setMiniAppConfig(String localMiniAppVersion, IMiniAppConfigCallback configCallback)
方法含義
SDK請求接入方從網(wǎng)絡(luò)上獲取當(dāng)前小程序的配置信息,接入方請求完畢后,將返回數(shù)據(jù)告知SDK(包括成功,失敗)
參數(shù)說明
屬性 | 類型 | 說明 |
---|---|---|
localMiniAppVersion | String | 本地數(shù)據(jù)庫中當(dāng)前小程序的版本,用于網(wǎng)絡(luò)請求中請求版本參數(shù) |
configCallback | IMiniAppConfigCallback | SDK提供給接入方的設(shè)置配置數(shù)據(jù)的接口引用 |
具體處理
接入方獲取當(dāng)前的小程序配置信息 請求參數(shù)有兩個
1.
code
:當(dāng)前小程序的識別碼
2.
version
:當(dāng)前小程序的版本,值為回調(diào)中的參數(shù)localMiniAppVersion
.
具體網(wǎng)絡(luò)接口的詳細(xì)說明,請查看
小程序服務(wù)端文檔
當(dāng)配置接口請求完成后,進(jìn)行如下的轉(zhuǎn)換,將請求結(jié)果告知SDK
//response:配置接口請求返回的Json格式的數(shù)據(jù)
String responseJsonString = "{...}";
Map configMap = new Gson().fromJson(responseJsonString, Map.class);
configCallback.setMiniAppConfigJsonString(map);
下載小程序離線包
說明:SDK通知接入方下載離線包,并將下載后的結(jié)果告知SDK
在回調(diào)中的setOfflinePackagePath
方法中觸發(fā)
下面對setOfflinePackagePath
方法進(jìn)行詳細(xì)說明: 1.方法含義
public void setOfflinePackagePath(String appId, String fullDownloadUrl, String offlinePackageStorageDirectory, String offlinePackageName, IMiniAppOfflinePackageDownloadCallback downloadCallback)
SDK通知接入方下載離線包,并將下載后的結(jié)果告知SDK
參數(shù)說明
屬性 | 類型 | 說明 |
---|---|---|
appId | String | 小程序id |
fullDownloadUrl | String | 小程序全量離線包下載地址url |
offlinePackageStorageDirectory | String | 下載完成后離線包的存儲目錄 |
offlinePackageName | String | 下載后離線包需要重命名的名字 |
downloadCallback | IMiniAppOfflinePackageDownloadCallback | SDK提供給接入方的下載完成接口引用 |
具體處理
1.接入方使用fullDownloadUrl
進(jìn)行離線包下載
2.下載成功后,將離線包重新命名為
offlinePackageName
,將其保存在offlinePackageStorageDirectory
這個路徑下
3.下載成功調(diào)用
downloadCallback.setOfflinePackagePath(offlinePackagePath+"/"+offlinePackageName);
方法
4.下載失敗后調(diào)用
downloadCallback.downloadError(errorMsg)
,其中errorMsg為下載失敗的原因
小程序請求登錄
說明:SDK請求接入方進(jìn)行登錄,然后將結(jié)果告訴SDK
這個會在回調(diào)中的requestLogin
方法中觸發(fā)。
下面對requestLogin
方法進(jìn)行詳細(xì)說明 方法含義
public void requestLogin(String appId, IMiniAppLoginCallback loginCallback)
SDK請求接入方進(jìn)行登錄,然后將結(jié)果告訴SDK
參數(shù)說明
屬性 | 類型 | 說明 |
---|---|---|
appId | String | 小程序id |
loginCallback | IMiniAppLoginCallback | SDK提供給接入方的登錄完成后回調(diào)的接口引用 |
具體處理
登錄成功:
//1.登錄后服務(wù)端返回的數(shù)據(jù)(為Json格式的字符串)
String responseSuccessJsonString = "{}";
//2.將Json格式的字符串轉(zhuǎn)換為Map
Map mapSuccess = new Gson().fromJson(responseSuccessJsonString, Map.class);
//3.調(diào)用loginCallback.setLoginSuccess()方法
loginCallback.setLoginSuccess(mapSuccess);
登錄失敗
//1.登錄后服務(wù)端返回的數(shù)據(jù),為Json格式的字符串
String responseErrorJsonString = "{}";
//2.將Json格式的字符串轉(zhuǎn)換為Map
Map mapError = new Gson().fromJson(responseErrorJsonString, Map.class);
//3.調(diào)用loginCallback.setLoginError()方法
loginCallback.setLoginError(mapError);
小程序請求接口轉(zhuǎn)發(fā)
說明:小程序內(nèi)網(wǎng)絡(luò)請求的轉(zhuǎn)發(fā),請進(jìn)行網(wǎng)絡(luò)請求,并將結(jié)果告訴SDK
這個在回調(diào)中的requestNetWork
方法中觸發(fā)。
方法含義
public void requestNetWork(String appId, String accessName, String forwardInfoJsonString, IMiniAppNetWorkForwardCallback forwardCallback)
小程序內(nèi)網(wǎng)絡(luò)請求的轉(zhuǎn)發(fā),請進(jìn)行網(wǎng)絡(luò)請求,并將結(jié)果告訴SDK
參數(shù)說明
屬性 | 類型 | 說明 |
---|---|---|
appId | String | 小程序id |
accessName | String | 拼接URL時使用 |
forwardCallback | IMiniAppNetWorkForwardCallback | SDK提供給接入方的接口轉(zhuǎn)發(fā)完成后回調(diào)的接口引用 |
具體處理
請求URL的完整格式為:
String wholeUrl = host + accessName + api;
例如: 轉(zhuǎn)發(fā)接口的
host
如下:
String host = "http://197.3.156.92:41302";
請求轉(zhuǎn)發(fā)的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的格式參數(shù)說明
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"
}
字段含義說明
屬性 | 類型 | 默認(rèn)值 | 必填 | 說明 | 最低版本 |
---|---|---|---|---|---|
url | string | 是 | 開發(fā)者服務(wù)器接口地址 | ||
data | string/object | 否 | 請求的參數(shù) | ||
method | string | POST | 否 | HTTP 請求方法 | |
dataType | string | json | 否 | 返回的數(shù)據(jù)格式 | |
responseType | string | text | 否 | 響應(yīng)的數(shù)據(jù)類型 | |
encrypted | boolean/string | false | 否 | 是否加密 | |
cipherFlag | string | 否 | 加密方式 |
method 參數(shù)的合法值
值 | 說明 | 最低版本 |
---|---|---|
GET | HTTP 請求 GET | |
POST | HTTP 請求 POST |
dataType 參數(shù)的合法值
小程序sdk不用關(guān)心,前端處理
值 | 說明 | 最低版本 |
---|---|---|
json | 返回的數(shù)據(jù)為 JSON,返回后會對返回的數(shù)據(jù)進(jìn)行一次 JSON.parse | |
其他 | 不對返回的內(nèi)容進(jìn)行 JSON.parse |
responseType 參數(shù)的合法值
值 | 說明 | 最低版本 |
---|---|---|
text | 響應(yīng)的數(shù)據(jù)為文本 |
encrypted 參數(shù)的合法值
值 | 說明 | 最低版本 |
---|---|---|
false或者空 | 不加密 | |
true | 加密 |
cipherFlag 參數(shù)的合法值
encrypted為false或空時不傳該字段
值 | 說明 | 最低版本 |
---|---|---|
002 | 登陸后交易使用的加密 | |
005 | 登陸前交易使用的加密 |
success 回調(diào)參數(shù):
屬性 | 類型 | 說明 | 最低版本 |
---|---|---|---|
data | string/Object/Arraybuffer | 開發(fā)者服務(wù)器返回的數(shù)據(jù) | |
statusCode | number | 開發(fā)者服務(wù)器返回的 HTTP 狀態(tài)碼 | |
header | Object | 開發(fā)者服務(wù)器返回的 HTTP Response Header |
fail 回調(diào)參數(shù):
屬性 | 類型 | 說明 | 最低版本 |
---|---|---|---|
error | Object | 開發(fā)者服務(wù)器返回的錯誤信息,包括code錯誤碼, msg錯誤信息字段 |
那么轉(zhuǎn)發(fā)請求的完整的URL如下:
JSONObject forwardInfoJsonObject = new JSONObject(forwardInfoJsonString);
String api = forwardInfoJsonObject.optString("api");
String wholeUrl = host + accessName + api;
小程序錯誤回調(diào)
說明:小程序SDK統(tǒng)一的錯誤回調(diào),包括接入方傳入的參數(shù)不合法,包括SDK內(nèi)部的異常. 這個在回調(diào)中的
miniAppError
方法中觸發(fā)
下面對miniAppError
方法進(jìn)行詳細(xì)說明: 方法含義
小程序SDK統(tǒng)一的錯誤回調(diào),包括接入方傳入的參數(shù)不合法,包括SDK內(nèi)部的異常
參數(shù)說明
public void miniAppError(final int error_code, final String error_msg)
error_code:錯誤碼 error_msg:錯誤信息
具體處理
//可以使用Toast,方便調(diào)試和錯誤調(diào)試
Toast.makeText(MainActivity.this, error_code + ":" + error_msg, Toast.LENGTH_LONG).show();
錯誤碼說明
錯誤碼 | 說明 |
---|---|
100 | 配置接口傳遞的map==null |
101 | 配置接口返回數(shù)據(jù)錯誤 |
102 | 配置接口返回Json數(shù)據(jù)異常! 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 不是一個數(shù)字 |
111 | 小程序配置Json中 accessName is empty |
112 | 小程序配置Json中 miniAppIdAlias is empty |
200 | 當(dāng)前SDK不支持該小程序,請升級SDK版本 |
201 | 客戶端獲取Config信息失敗 |
300 | 客戶端下載離線包失敗 |
301 | 客戶端傳遞的小程序離線包存儲地址為空 |
302 | 小程序離線包不存在 |
303 | 小程序離線包,壓縮文件md5值和配置接口中返回的不一致 |
304 | 小程序解壓目錄中沒有文件 |
305 | 小程序解壓失敗 |
306 | 解壓文件中包含非法字符 |
400 | 加載的文件中出現(xiàn)了sha1不一致的情況 |
小程序生命周期
說明:小程序SDK對外提供生命周期的兩個回調(diào)。分別是開始加載和關(guān)閉。 分別對應(yīng)著回調(diào)中的
miniPageOnStart
方法和miniPageOnDestroy
方法
下面分別對這兩個方法進(jìn)行詳細(xì)的說明
回調(diào)中的miniPageOnStart
方法
方法含義
public void miniPageOnStart(String appId)
小程序界面開始加載的回調(diào).
參數(shù)說明
屬性 | 類型 | 說明 |
---|---|---|
appId | String | 小程序id |
具體處理
可以根據(jù)自己的業(yè)務(wù),進(jìn)行統(tǒng)計等等處理.
回調(diào)中miniPageOnDestroy
方法
方法含義
public void miniPageOnDestroy(String appId)
小程序界面關(guān)閉的回調(diào).
參數(shù)說明
屬性 | 類型 | 說明 |
---|---|---|
appId | String | 小程序id |
具體處理
可以根據(jù)自己的業(yè)務(wù),進(jìn)行統(tǒng)計等等處理.
小程序日志控制
SDK提供了Log日志開關(guān)的方法MiniAppLog.setDebug()
SDK內(nèi)部的日志,默認(rèn)是開著的,建議在release模式下關(guān)閉日志。
if (!BuildConfig.DEBUG){
MiniAppLog.setDebug(false);
}
小程序版本
SDK提供獲取當(dāng)前的版本號,方便調(diào)試。
MiniAppSDK.getInstance().getSDKVersionName();