參考視頻：docs.apicloud.com/APICloud/videos-and-codes

第一章 SDK簡介

AndroidStudio版模塊包是標準的AAR包。APICloud模塊擴展SDK是基于DeepEngine（以下稱引擎）開放的一套標準化擴展機制，用于支持開發(fā)者靈活擴展任意原生功能到APICloud平臺。 平臺現有的模塊如果無法滿足您的需求，可通過該SDK進行模塊擴展，在多個項目中復用，為應用開發(fā)節(jié)省大量的重復性工作，您也可以將開發(fā)完成的模塊提交到模塊商店，分享給開發(fā)者使用。 本SDK提供給有一定Android原生開發(fā)基礎的開發(fā)者，通過簡單的接口實現和標準的Android開發(fā)流程，快速擴展模塊，輕松接入APICloud平臺。

一個完整的SDK包命名類似：ModulesDevProject_Android.zip。解壓后是一個標準的Android Studio工程目錄，如圖所示：

第二章 閱讀對象

本文檔面向所有使用該SDK的Android開發(fā)人員、測試人員、合作伙伴以及對此感興趣的其他用戶。閱讀該文檔要求用戶熟悉Android應用開發(fā)，熟悉Android Studio開發(fā)工具的基本使用，并且對Html、CSS、Javascript有一定了解，熟悉Java和Javascript中JSON格式數據的操作。

第三章 SDK功能說明

本SDK是開發(fā)者快速了解使用APICloud跨平臺移動應用開發(fā)引擎，并熟練掌握模塊開發(fā)技巧及了解APICloud移動應用云平臺的橋梁。

i.框架設計

引擎通過實現對操作系統(tǒng)底層能力的封裝和擴展，基于H5引擎開放API給JS調用的形式，實現了HTML+CSS+JS開發(fā)語言和Object-C/Java/C/C++等原生開發(fā)語言之間的橋接，極大的豐富和增強了標準H5的能力。令前端開發(fā)者通過JS即可調用移動設備的底層功能，如：電話、短信、定位、多媒體、跨域http請求等，并能將如百度地圖、支付寶等第三方廠商的SDK很容易的集成至App中來。

本SDK開放橋接機制，方便具有一定Android基礎的開發(fā)者靈活擴展模塊，豐富JS的能力，提升App的用戶體驗。引擎框架橋接層設計如圖：

ii. 主要功能

本SDK主要提供以下功能和接口：

• 映射一個Java類的函數和常量（統(tǒng)稱為模塊module）至Javascript對象的函數和常量，包括：

-被映射Java類的函數、屬性及常量書寫規(guī)范

-module.json文件的聲明

• 往當前屏幕window中插入/移除一個或者多個自定義View，包括：

-直接插入View至window

-獲取一個Activity的View并插入window

• 在module中啟動另一個Activity或App并獲取回調，包括：

-直接啟動Activity

-啟動Activity并獲取返回值

• 啟動widget、向window注入Javascript，包括：

-在module中調用引擎的widget管理能力啟動widget

-向APP的某活動window注入并執(zhí)行一段Javascript

• 擴展模塊生命周期的管理：

-動態(tài)初始化和分配內存

-生命周期事件回調等

第四章 開發(fā)前準備

i. 開發(fā)環(huán)境：

PC：Windows XP/Win7/8/10 Mac OS；

JDK1.8及以上，默認使用1.8；

Android Studio3.0及以上；

Gradle5.6.4及以上（對應官方gradle-5.6.4-all.zip），Gradle插件版本3.6.1。建議提前下載好Gradle，并在開發(fā)工具中設置使用本地離線的Gradle；

Android SDK 21（5.0）及以上，建議使用30；

Android Studio下載地址：https://developer.android.google.cn/studio/index.html

ii. 開發(fā)幫助參考：

詳細的SDK幫助文檔：docs.apicloud.com/superwebview/Android/（未處理）

Android在線API文檔:https://developer.android.google.cn/reference/packages.html

Javascript規(guī)范及入門：http://www.w3school.com.cn（未處理）

JSON數據在線Viewer：http://www.bejson.com/go.html?u=http://www.bejson.com/jsonview2/(未處理)

第五章 使用SDK進行模塊開發(fā)

i. 導入SDK工程到Android Studio

• 解壓ModulesDevProject_Android.zip至任意目錄
• 在Android Studio中導入該SDK，操作步驟：Studio ->File ->Oepn ->選擇1中解壓的目錄 ->Ok即可。

將項目管理視圖切換為“project”，導入后的工程結構如圖：

ii. 開始開發(fā)模塊

1.創(chuàng)建模塊

APICloud模塊包為標準的AAR包，遵循Studio的模塊開發(fā)流程。在項目APICloudModuleSDK上右鍵 ->New ->Module，為項目新建一個Module，并命名為moduleDemo，如圖：

創(chuàng)建完畢后項目結構如圖：

2.在項目中配置引用模塊

在app的build文件中配置引用moduleDemo模塊，操作步驟：打開app ->build.gradle，在dependencies中加入引用

compile project(':moduleDemo')

如圖：

3.在模塊中配置引用引擎jar包

在moduleDemo模塊的build文件中配置引用引擎的jar包，操作步驟：打開moduleDemo ->build.gradle，在dependencies中加入引用

provided files('../app/libs/apiEngine v1.1.0.jar')

注意：使用provided進行引用，即僅依賴引用，但不會被編譯到AAR中

如圖：

4.創(chuàng)建用于綁定映射至JS對象的Java類

在moduleDemo模塊中新建Java類（以下以APIModuleDemo.java類為例，映射的JS對象為moduleDemo），繼承自引擎Jar包中的APIModule或者UZModule類，并重寫相關函數。如下圖：

5.在模塊聲明文件module.json中聲明Java類

開發(fā)者務必在module.json文件中聲明被映射Java類的class路徑，以及其所開放給JS的模塊名稱，引擎將根據該配置檢索相應的Java類，并在適當時候將其初始化。

module.json文件固定存放于app下的assets/uzmap目錄中，如圖：

存儲格式為JSON格式，包含modules、name、class等字段。聲明標準如下：

{
    "modules":[
        {
        "name":"moduleDemo",
        "class":"com.apicloud.moduleDemo.APIModuleDemo"
        },
        {
        "name":"xxxDemo",
        "class":"com.xxx.Objxxx"
        },
        {
        "name":"xxxDemo1",
        "class":"com.xxx.Objxxx1"
        }
    ]
}

字段解釋：

• name：定義該擴展模塊開放給JS的模塊對象名，類似于標準JS中的window、document、Math等對象。
• class：定義該擴展模塊對應綁定至JS的Java類及其路徑。

6.定義開放API

若希望將Java類中的某個函數開放給JS調用，只需將該函數聲明以“jsmethod_”開頭，并且聲明該函數為public，同時接收且僅接收一個類型為UZModuleContext的參數即可。

函數聲明格式：

public void jsmethod_func(final UZModuleContextmoduleContext){


}

引擎會在初始化的時候，根據Java函數是否包含“jsmethod_”的前綴，而將該函數映射至JS對象。例如聲明“jsmethod_showAlert”，引擎會將“jsmethod_showAlert”函數映射至模塊對應JS對象的“showAlert”函數，開發(fā)者在Html頁面中即可使用moduleDemo.showAlert(argument)的方式直接調用至Java的jsmethod_showAlert函數，并進行相關操作。

如下圖中的定義：

實現了向JS對象映射：

• showAlert：彈出一個對話框，接收定義為“msg”字段的參數作為對話內容；

對應在JS中使用：

• moduleDemo.showAlert(argument)；

即可調用到對應的Java函數中；

注意：

以“jsmethod_”前綴聲明的Java函數，引擎默認在UI線程中操作該函數，因此請勿在該函數內部做耗時的操作，避免引起UI阻塞，拋出異常，耗時操作可另起線程進行。

7.獲取來自JS傳入的參數

擴展機制規(guī)范要求前端JS開發(fā)者必須使用JSON格式數據作為JS與原生（Java）之間交換數據的傳參。引擎將對JS傳入的參數進行處理并封裝，通過包裝成UZModuleContext類傳遞給聲明“jsmethod_”前綴的函數。

UZModuleContext類是JS與原生（Java）之間通信的運行時上下文封裝，既是JS提交給Java數據的載體，同時也是Java回調JS的執(zhí)行者。UZModuleContext內部封裝了JSON數據操作的所有方法，如optInt、optString等，UZModuleContext同時還封裝了success、error等回調JS的方法。

例如Html頁面代碼為：

uzmoduledemo.showAlert({msg:"Hello APICloud!"});

在Java中可通過類似如下方式獲取JS傳入的msg值：

public void jsmethod_showAlert(final UZModuleContext moduleContext){
    String showMsg = moduleContext.optString("msg");
}

8.將操作結果回調至JS

JS與原生之間遵循異步訪問機制，Java做完相關操作后，應該將操作結果回調給JS，或者通知JS本次操作成功與否，錯誤提示等。該回調過程由UZModuleContext下的success、error等函數完成。如下代碼實現了對“showAlert”結果的回調，將用戶點擊對話框按鈕的操作通知JS：

JSONObject ret = new JSONObject();
try {
    ret.put("buttonIndex", 1);
} catch (JSONException e) {
    e.printStackTrace();
}
moduleContext.success(ret, true);

ii. 導出模塊包

1.導出模塊包

模塊開發(fā)調試完畢后，需將該模塊編譯為AAR包，并按照APICloud模塊包要求打包，通過APICloud網站控制臺提交。 打包步驟：

• 將當前項目焦點聚在將要導出的模塊上，并在工具欄依次操作Build ->Make Module 'xxxModule'。如下圖：

• 編譯完畢，進入該模塊的build/outputs/aar/目錄，將其中的“xxxModule-release.aar”文件拷貝。如圖：

• 新建文件夾，命名為你的模塊名，比如“moduleDemo”，將“xxxModule-release.aar”粘貼至該文件夾，同時在該目錄下新建名為“module.json”的json文件，并將app中聲明的模塊配置拷貝到該文件中，例如：

  {
  "name":"moduleDemo",
  "class":"com.apicloud.moduleDemo.APIModuleDemo"
  }

• 最終模塊包結構如圖：

• 如果你的模塊還依賴其他AAR，也需要將這些AAR復制粘貼至該文件夾，包含到模塊包里。例如，你的模塊依賴support-vector-drawable-24.0.0.aar，最終模塊包目錄文件將如圖所示：

• 將“moduleDemo”文件夾壓縮為標準zip格式的文件：

• 通過APICloud網站控制臺上傳自定義模塊即可使用：

第六章 模塊開發(fā)Demo簡介

本SDK默認展示5個擴展模塊demo。其中：

• moduleDemo演示一個擴展模塊的完整過程。擴展一個名為moduleDemo的JS對象，并將該對象映射至Java類（APIModuleDemo）的過程，同時展示如何在html頁面中通過JS調用該模塊。APIModuleDemo類下每個API都有詳細注釋及使用實例，請開發(fā)者仔細閱讀，同時請關注assets/widget目錄下html頁面的書寫內容。
• moduleRefresh演示如何進行下拉刷新模塊的開發(fā)。
• moduleScrollPicture演示如何進行UI類模塊的開發(fā)，并實現了類似UIScrollPicture模塊的輪播圖效果功能。
• eventdemo演示如何使用ApplicationDelegate類監(jiān)聽整個應用的生命周期，并進行相關的操作。
• syncInterface樣式如何進行同步API的擴展。

第七章 SDK主要API簡介

本章節(jié)提供引擎所有與模塊擴展相關的API說明。

i.類

本SDK開放數個關鍵類：APIModule(UZModule)、ApplicationDelegate、UZModuleContext、ModuleResult、RefreshHeader，以及若干工具類API及常量，如：UZUtility、APICloudHttpClient等。

ii.重要API

APIModule(UZModule)對象：

UZModuleContext對象：

第八章 模塊包特別說明

• 模塊應將其所依賴的所有外部資源盡量包含在AAR中，避免通過compile或implementation引用

• module.json文件，其內容必須如下：

  {
  "name":"moduleDemo",
  "class":"com.apicloud.moduleDemo.APIModuleDemo"
  }

如果一個模塊包中包含多個模塊入口，則配置類似如下：

  {
  "name":"moduleDemo",
  "class":"com.apicloud.moduleDemo.APIModuleDemo"
  },
  {
  "name":"moduleDemo1",
  "class":"com.demo.ModuleDemo1"
  },
  {
  "name":"moduleDemo2",
  "class":"com.demo.ModuleDemo2"
  }

ii. 模塊兼容AndroidX

• APICloud云編譯依賴的android支持庫默認為support-v4:26.0.0版本，如果您的模塊希望依賴androidx作為支持庫，則需要在模塊導出的aar中增加相應的標識。 具體做法：在相應模塊AndroidManifest.xml的manifest節(jié)點下增加name為“android.useAndroidX”的meta-data，并將value置為true，如下圖所示。

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.apicloud.sdk.moduledemo">


    <uses-sdk android:minSdkVersion="15" android:targetSdkVersion="28"/>


    <uses-permission android:name="android.permission.VIBRATE" />


    <meta-data android:name="android.useAndroidX" android:value="true" />


    <application>


    </application>


</manifest>

云編譯在獲得模塊該標識后，將自動為當前所編譯項目增加androidx支持庫。

特別說明：如果模塊依賴androidx，將觸發(fā)apk依賴庫從support遷移到androidx，對用戶編譯的apk可能存在潛在風險，應在模塊文檔中明確告知模塊使用者。

第九章 其他

i.資源文件命名規(guī)范

建議開發(fā)者在開發(fā)過程中對資源文件的命名遵循如下規(guī)則：mo + 模塊名 + 功能或UI類型 + 資源類型。

例如（以moduleDemo模塊為例）：
命名一個布局資源文件：
mo_moduledemo_demo_activity_layout.xml


命名一個圖片資源文件：
mo_moduledemo_backbtn_press_bg.png
mo_moduledemo_layout_bg.png


命名一個字符資源文件：
mo_moduledemo_init_msg
mo_moduledemo_error_msg

特別說明：SDK工程目錄下的任意原有資源文件，開發(fā)者不應隨意改動，需保持其原狀，否則SDK可能在啟動過程中報找不到引擎資源的警告而強制退出，或者破壞模塊開發(fā)環(huán)境與云編譯環(huán)境的一致性。

ii.其他說明

在開始模塊開發(fā)之前，建議閱讀《開發(fā)模塊設計規(guī)范》（未處理）。

第十章 模塊審核規(guī)范

開發(fā)者開發(fā)的模塊務必遵守《模塊審核規(guī)范-Android》（未處理）。