SuperWebview開發指南Android

本文件面向所有使用該SDK的開發人員、測試人員、管理人員以及對此感興趣的其他使用者。閱讀該文件要求使用者熟悉Android應用開發，瞭解APICloud平臺，如果能對HTML/CSS/JavaScript有一定了解則更好。

第一章 簡介

SuperWebview是APICloud官方推出的另一項重量級API生態產品，以SDK方式提供，致力於提升和改善移動裝置Webview體驗差的整套解決方案。APP通過嵌入SuperWebview替代系統Webview，即可在Html5中使用APICloud平臺現有的所有端API，以及包括增量更新、版本管理、資料雲、推送雲、統計分析、積木式模組化開發、所有已經聚合的開方平臺服務等在內的雲服務能力，增強使用者體驗，解決移動裝置Webview使用過程中出現的相容能力弱、載入速度慢、功能缺陷等任何問題，幫助開發者解決使用Webview過程中的所有痛點。

SuperWebview繼承APICloud終端引擎的包括跨平臺能力，模組擴充套件機制，生命週期管理，視窗系統，事件模型，APP級別的使用者體驗等在內的所有優秀能力，並且全面打通Html5與Android和IOS之間的互動，同步提供APICloud平臺最新的API技術能力和服務，APICloud團隊將保持對SuperWebview的持續更新和優化，相容Html5的新特性，持續推出優質服務。

第二章 架構設計

2.1 架構設計

SuperWebview是APICloud終端引擎另一種形態下的開放API，提供“NativeView佔主導，SuperWebview層疊輔助”的混合能力，旨在幫助企業或者個人開發者已有的Android和IOS專案提供基於Html5能力的快速業務擴充套件，無縫使用APICloud雲端一體能力提供的優質技術服務，同時保證最優的使用者體驗。您可以將APP中的某個或多個模組使用SuperWebview進行實現，您甚至可以將SuperWebview SDK當作獨立的APP快速開發框架在混合開發中使用。結合APICloud終端引擎的跨平臺能力和各項雲服務能力，解決諸如跨平臺，增量更新，快速版本迭代等APP開發過程中常見的痛點。

SuperWebview整體API開放架構設計如下：

2.2 基本能力

SuperWebview在繼承系統Webview介面能力的基礎上，主要提供以下功能的介面：

1. API訪問許可權控制管理功能
2. Android/IOS與Html5之間事件/資料互動功能
3. Web與Native介面直接的混合佈局和混合渲染功能
4. 加速資料載入、點選響應和滾動速度
5. 常用手勢支援、介面切換動畫
6. 訪問資源控制管理功能
7. 執行Html5中指定Javascript指令碼功能
8. 模組擴充套件功能，該功能繼承自APICloud終端引擎的模組擴充套件能力
9. Android&IOS開發中常用的網路請求框架，快取管理等工具介面
10. 統一的生命週期管理，視窗系統，使用者體驗

第三章 使用準備和流程

3.1 執行環境

3.1.1 軟硬體環境及要求

1. 本SDK要求最低Android系統版本為：2.3，Google API級別為9
2. 本SDK要求APP開啟硬體加速，如關閉，會對渲染效率有一定的影響
3. 本SDK要求Android開發環境配置Android SDK（ADT）的最低版本為5.0，Google API級別為21
4. 本SDK依賴Google提供的最新版的相容包，即最新版的android-support-v4.jar

3.1.2 必須的許可權：

使用SuperWebviewSDK的APP專案，必須在AndroidManifest中申請如下許可權：

1, 訪問網路

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

2, 寫外部儲存

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

3, 獲取運營商資訊，用於支援提供運營商資訊相關的介面

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

4, 訪問wifi網路資訊

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

5, 讀取手機當前的狀態

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

3.2 獲取SuperWebview SDK

3.2.1 建立和編譯SDK

1, 登入APICloud官網：http://www.apicloud.com，註冊成為APICloud開發者

2, 進入控制檯，在“概覽”介面新建APP專案，如截圖：

3, 點選控制檯左側的“模組”選項卡，導航至模組選擇介面，如截圖：

勾選您的專案中將要用到的模組，如果不需要，則略過此步驟。

4, 點選控制檯左側的“SuperWebView”選項卡，導航至SDK編譯介面，勾選您需要編譯的平臺，如截圖：

5, 點選“編譯SDK”按鈕，開始進行SDK的編譯，等待片刻，編譯完成後，頁面中將展示SDK的下載連結，如截圖：

6, 點選其中的下載連結，下載對應平臺的SDK包至本地，並解壓

3.3 SuperWebview SDK包簡介

本SDK為一個壓縮檔案包，其中包含SDK包一份（lib）、示例程式碼工程一份（Samples）、文件包一份（Docs），可能還包含一份更新說明。基本目錄結構如下：

3.3.1 lib目錄

lib目錄下包含您在APICloud網站控制檯編譯的SDK包的所有資源，包括程式碼的jar包，so庫，必須的資原始檔，AndroidManifest.xml檔案，在使用過程中需要將這些檔案依次拷貝到您的APP專案中。lib目錄下共包含libs、res、以及AndroidManifest.xml檔案，可能還包含一個assets目錄：

其中：

libs目錄下為APICloud引擎及所勾選模組的jar和so庫；

res目錄下為APICloud引擎及所勾選的模組所需的資原始檔，包括xml，圖片等檔案；

assets目錄下為APICloud引擎及所勾選模組需要的assets型別資原始檔；

AndroidManifest.xml檔案包含了APICloud引擎及所勾選的模組所需的許可權、Activity、Service等配置

3.3.2 Docs目錄

Docs目錄下包含本“開發者使用指南”以及一份html格式的詳細API幫助文件，在開發過程中可隨時參考該文件，獲取滿足您APP業務所需的各種API。

3.3.3 Samples目錄

Samples目錄下為使用本SDK的幾個不同場景下的Demo，包含詳細的程式碼註釋。包含以下第四章中程式碼示例中的專案ProjectFirst。

第四章 開始嵌入SDK到APP

以下操作過程中，假設您現有或者新建的APP專案名稱為“ProjectFirst”。 解壓下載得到的SDK包到本地，得到lib、Docs、Samples等資料夾

4.1 新增SDK到APP工程

1. 將lib/libs目錄下的so庫和Jar包拷貝到ProjectFirst中對應的libs目錄下及armeabi目錄中

2. 將lib/res目錄下的所有資原始檔拷貝到ProjectFirst中對應的res同名目錄中，注意values型別資源的合併

3. 將lib/AndroidManifest.xml檔案中的所有permission、activity、provider、service、receiver等全部拷貝到ProjectFirst中對應的AndroidManifest中

4. 如果有lib/assets目錄，則將lib/assets目錄下的所有資原始檔拷貝到ProjectFirst中對應的assets目錄中

4.2 開始使用API

4.2.1 初始化SDK

SuperWebview SDK中的所有API必須在顯式的呼叫初始化函式後才能使用，建議在您專案入口Application的onCreate函式中呼叫APICloud.initialize(Context)進行初始化。如果您的專案沒有Application，可以新建一個類繼承自Application，並在AndroidManifest中配置該類。比如MyApplication：

package com.sdk.samples;

import android.app.Application;
import com.uzmap.pkg.openapi.APICloud;

public class MyApplication extends Application{

    @Override
    public void onCreate() {
        super.onCreate();
        APICloud.initialize(this);//初始化APICloud，SDK中所有的API均需要初始化後方可呼叫執行
    }
}

同時在AndroidManifest的application節點配置該類為其name屬性：

<application
        android:name="com.sdk.samples.MyApplication"
        android:icon="@drawable/ic_logo"
        android:label="@string/app_name">

4.2.2 使用SuperWebview

新建Activity類，繼承自ExternalActivity（ExternalActivity的幫助說明請參考第五章重要API說明中的介紹，或者閱讀API文件中的詳細介紹）。假設ProjectFirst專案中某版塊是通過使用Android標準API中的Webview載入遠端伺服器的Html5頁面所實現，該版塊所在Activity為WebPageModule類，則將該類改造為繼承自ExternalActivity類即可，或者自行新建WebPageModule類繼承自ExternalActivity：

    package com.sdk.samples.apicloud;

import android.os.Bundle;
import com.uzmap.pkg.openapi.ExternalActivity;

/**
 * 
 * 您原專案中載入遠端Html5頁面的版塊，現用SuperWebview替換<br>
 * 使用SuperWebview的Activity，需繼承自ExternalActivity
 * @author dexing.li
 *
 */
public class WebPageModule extends ExternalActivity {

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
    }
}

同時，在AndroidManifest中配置WebPageModule：

<activity android:name="com.sdk.samples.apicloud.WebPageModule" 
            android:screenOrientation="portrait" 
            android:windowSoftInputMode="adjustResize" 
            android:theme="@android:style/Theme.Translucent.NoTitleBar" 
            android:configChanges="orientation|locale|keyboardHidden|screenLayout|screenSize|smallestScreenSize|keyboard" />

此外，您可以通過重寫ExternalActivity下的shouldOverrideUrlLoading，onPageStarted，onPageFinished等函式，實現SuperWebview與您專案原有業務的對接。

4.2.3 Html5程式碼的編寫和配置

在ProjectFirst專案的assets目錄下新建名為widget的目錄，並在該目錄下新建名為config的xml檔案，config.xml檔案要求編碼為無BOM頭UTF-8編碼，如圖：

關於widget目錄的詳細介紹，請登入APICloud網站參考《Widget包結構說明》文件。

關於config.xml檔案的詳細說明及配置，請登入APICloud網站參考《APICloud應用配置說明》文件。

配置完成後，開始編寫第一張Html頁面，例如index.html，並將其在config.xml中配置為content欄位，即宣告該Html為SuperWebview的預設入口Html頁：

<?xml version="1.0" encoding="UTF-8"?>
<widget id="A0000000000000" version="0.0.1"> 
  <name>ProjectFirst</name>  
  <content src="index.html"/>  
  <access origin="*"/> 
</widget>

index.html的詳細程式碼請閱讀Samples中的程式碼，其他Html程式碼的編寫，按照您的產品設計進行即可。

關於Html程式碼的編寫，也可通過下載APICloud開發工具進行專案的建立，編碼，除錯，開發完成後直接將整個專案的程式碼拷貝到ProjectFirst中的assets/widget目錄下即可。使用APICloud開發工具開發，可為配合第七章高階功能中的某些操作提供基礎。

4.2.4 啟動SuperWebview

在ProjectFirst中任意介面中，通過響應某可點選介面元素的點選事件，啟動WebPageModule這個Activity即可：

    @Override
    public void onClick(View v) {
        //實現由之前的載入遠端webapp的體驗，轉向由SuperWebview提供的原生APP體驗
        if(v == mButtonWeb){
            Intent intent = new Intent(getContext(), WebPageModule.class);
           getContext().startActivity(intent);
        }
    }

啟動完Activity後，接下來Html頁面的載入，渲染，邏輯執行等，SuperWebview會自動幫您完成。 通過SuperWebview提供的APICloud終端引擎的能力，您基於Html的頁面，可以無縫使用APICloud雲端一體能力中提供的所有API，達到原生APP級別的使用者體驗

接下來您可以通過結合第五章中的重要API說明以及SuperWebview的API文件來擴充您APP的各種場景下使用SuperWebview的能力。

第五章 重要API功能

本章節提供SuperWebview SDK中幾個重要API的簡單幫助說明，詳細API文件請參考附件中的API文件包。 本SDK開放的API主要位於“com.uzmap.pkg.openapi.”以及“com.uzmap.pkg.uzkit.”路徑下。

“com.uzmap.pkg.openapi.*”中主要包含提供SuperWebview SDK能力的Activity等UI元件相關的類，主要包括4個重要的開放類：APICloud，ExternalActivity，Html5EventListener，WebViewProvider

“com.uzmap.pkg.uzkit.*”中主要包含一些工具類，如HTTP網路請求，Html5相關工具函式，快取處理工具等。

5.1 openapi相關API類簡介

類	描述及函式原型
APICloud	提供了所有使用SuperWebview的靜態方法，在使用本SDK下的所有函式前，必須呼叫APICloud.initialize(Context)函式初始化終端引擎
ExternalActivity	SuperWebview開放的基本UI元件Activity，您專案中任何使用SuperWebview能力的Activity必須繼承自該Activity。該類繼承自系統Activity，主要包括以下開放API：  1. evaluateJavascript(String) 向某個window或者frame執行一段JS指令碼  2. addHtml5EventListener(Html5EventListener) 設定一個Html5事件監聽器，監聽來自Html5頁面廣播出來的事件  3. removeHtml5EventListener(Html5EventListener) 移除一個Html5事件監聽器  4. removeAllHtml5EventListener() 移除所有Html5事件監聽器  5. sendEventToHtml5(eventName, extra) 傳送一個事件並廣播給當前所有已載入的Html5頁面，如果其中有頁面監聽了該事件，它將收到廣播  6. onProgressChanged(WebViewProvider, progress) 當Html5頁面的載入進度發生變化時，引擎將通過該介面回撥給應用  7. onPageStarted(WebViewProvider, url, pageIcon) 當某個Html5頁面開始載入時，引擎將通過該介面回撥給應用  8. onPageFinished(WebViewProvider, url) 當某個Html5頁面載入結束時，引擎將通過該介面回撥給應用  9. shouldOverrideUrlLoading(WebViewProvider, url) 當引擎內部某個webview即將請求載入一個url時，將通過該介面通知應用，如果應用攔截並自行處理，引擎將不再處理該請求。  10. onReceivedTitle(WebViewProvider, title) 當引擎內部某個webview收到Html5頁面標題時，將通過該介面回撥給應用  11. shouldForbiddenAccess(host, module, api) 當某host地址的html頁面即將訪問某api時，將通過該介面通知應用，應用可以決定是否攔截，控制其不允許訪問  12. 如果啟動ExternalActivity實現的子類Activity時，Intent中傳入了“startUrl”欄位，那麼該Activity將自動以該startUrl配置的URL作為首頁載入入口。預設情況下使用widget/config.xml中的content欄位配置作為入口
Html5EventListener	Html5頁面事件監聽器，該監聽允許您監聽來自Html5頁面通過api.sendEvent發出的自定義事件廣播，實現原生應用與Html5之間的資料互動及解耦。 可通過ExternalActivity.addHtml5EventListener(Html5EventListener)進行註冊監聽 Html5事件將通過Html5EventListener.onReceive(WebViewProvider, Object)回撥
WebViewProvider	APICloud終端引擎中SuperWebview的代理類，內部包含一個APIWebview的例項。該類以代理的形式開放了webview的諸多API，如：  1. getName() 獲取webview所在frame的name，與api.openFrame時傳入的name對應，主window所在frame的name為固定值“main”  2. getWinName() 獲取webview所在window的name，與api.openWin時傳入的name對應，根window的name為固定值“root”  3. evaluateJavascript(script) 向該webview執行一段js指令碼  4. loadUrl(url) 請求該webview載入一條url  5. stopLoading() 要求當前webview停止載入  6. reload() 要求webview重新載入當前頁面  7. goBack() 要求當前webview回退歷史記錄  8. goForward() 要求當前webview前進歷史記錄

5.2 uzkit相關API類簡介

類	描述及函式原型
UZUtility	靜態工具函式庫，提供與Html5處理相關，APP相關的工具函式
request.APICloudHttpClient	APICloud終端引擎全域性標準HTTP請求處理類，包含：  request(Request) 插入一個http請求  cancelRequests(Object) 取消某個http請求  download(HttpDownload) 插入一個http下載請求  cancelDownload(Object) 取消某個http下載請求  disPlayImage(ImageOption, ImageView) 請求顯示遠端伺服器上的某張圖片資源到ImageView ….  等諸多HTTP資料請求相關的函式，非常方便客戶端向伺服器發起資料請求
request.Request	所有型別HTTP請求的超類
request.HttpGet	HTTP的GET請求類。通過APICloudHttpClient.request(HttpGet)發起
request.HttpPost	HTTP的POST請求類。通過APICloudHttpClient.request(HttpPost)發起
request.HttpDownload	HTTP的GET請求類，通常為請求下載非文字型別資料的大檔案。 通過APICloudHttpClient.download(HttpDownload)發起
request.HttpDelete	HTTP的DELETE請求類。通過APICloudHttpClient.request(HttpDelete)發起
request.HttpPut	HTTP的PUT請求類。通過APICloudHttpClient.request(HttpPut)發起
request.HttpHead	HTTP的HEAD請求類。通過APICloudHttpClient.request(HttpHead)發起
request.HttpOptions	HTTP的OPTIONS請求類。通過APICloudHttpClient.request(HttpOptions)發起
request.HttpPatch	HTTP的PATCH請求類。通過APICloudHttpClient.request(HttpPatch)發起
request.HttpTrace	HTTP的TRACE請求類。通過APICloudHttpClient.request(HttpTrace)發起
request.HttpParams	發起POST/PUT/PATCH請求時用於配置提交的資料
request.RequestCallback	HTTP請求的回撥，通過request.setCallback(callback)使用
request.HttpResult	HTTP請求的結果，通過RequestCallback.onFinish(HttpResult)回撥

第六章 其他

6.1 關於程式碼混淆：

如果開發者在釋出版本時需要混淆自己的程式碼，請在混淆檔案（一般預設為Android工程下proguard-project.txt或者proguard.cfg檔案）中新增如下說明：

-libraryjars libs/apiEngine {verion}.jar
-dontwarn  com.uzmap.pkg.*
-keep class  com.uzmap.pkg.** { *;}

其中，{version}為引擎jar包對應的版本

6.2 SDK固有資源說明及替換

原則上，SuperWebviewSDK中包含的任何XML、圖片等資原始檔，均需要原封不動的拷貝到您的專案中，如果熟悉APICloud平臺的開發者，則可在此基礎上替換或者更改這些資源，實現UI效果的自由定製。

第七章 高階功能

7.1增量更新（雲修復）

注意：使用雲修復功能的SuperWebview，您widget的config.xml中必須開啟“雲修復功能”，即config.xml中必須顯式的配置：為true

具體的使用流程：

1）、在左側控制檯選擇“雲修復”，進入雲修復頁面，在下拉選單中選擇“原生應用”，如截圖：

2）、選擇“原生應用”後，點選輸入框提示需要“手動輸入版本號”，如截圖：

3）、點選“手動輸入版本號”，如下圖所示. 其中，IOS要求輸入您應用的版本號（即Info.plist檔案中的CFBundleShortVersionString欄位值）； Android要求輸入您應用的versionCode（即AndroidManifest.xml檔案中的“android:versionCode”欄位值）；

4）、以ios版本為例：輸入版本號之後，需要選擇相對應的版本進行雲修復操作，如截圖：

選擇‘1.1.0’作為修復版本，如截圖：

5）、APICloud現支援兩種雲修復方式：提示修復、靜默修復。 更新包上傳方式分為：輸入修復內容的http更新地址或直接上傳更新壓縮包； 壓縮包格式要求為：根目錄名稱必須為widget，子目錄結構保持與APICloudStudio中專案目錄一致，並只保留更新的檔案，然後將widget目錄壓縮成.zip包即可：

下面以提示修復為例，選擇‘提示修復’中‘上傳更新檔案’如截圖：

上傳完成之後，點選右側‘更新’，成功之後會生成一條記錄，如截圖：

第八章 聯絡我們

如果以上資訊無法幫助您解決在開發中遇到的具體問題，請通過以下方式聯絡我們：

Email：

Tel：

WebSite：http://community.apicloud.com/bbs/