# 开发环境

  1. Android Studio 下载地址:Android Studio官网 OR Android Studio中文社区
  2. HBuilderX
  3. App离线SDK下载:最新android平台SDK下载

3.1.10版本起需要申请Appkey,具体请点击链接

# SDK目录说明

	|-- HBuilder-Hello				App离线打包演示应用
	|-- HBuilder-Integrate-AS		集成uni-app的最简示例
	|-- SDK							SDK库文件目录
	|-- Feature-Android.xls			Android平台各扩展Feature API对应的详细配置
	|-- Readme.txt					版本说明文件及注意事项
	|-- UniPlugin-Hello-AS			uni原生插件开发示例

# 准备工程

# 方式一:新建工程

打开Android studio新建一个空白项目

选择 Empty Activity 点击 Next。

avatar

Minimum API Level 建议选21及以上

Package name作为应用标志,涉及申请第三方平台账号,一般情况下不建议修改,包名一般设置反向域名,如:io.dcloud.HBuilder

点击 Finish 完成创建。

注意:App离线SDK不支持Kotlin

# 方式二:导入工程

2.7.0之后提供HBuilder-Integrate-AS工程,可以直接导入HBuilder-Integrate-AS工程,直接运行simpleDemo项目即可。

# 配置工程

  1. 基础库配置

    将lib.5plus.base-release.aar、android-gif-drawable-release@1.2.23.aar、uniapp-v8-release.aar、oaid_sdk_1.0.25.aar、install-apk-release.aar和breakpad-build-release.aar拷贝到libs目录下

    注意:HBuilder X 3.5.0及以上版本新增库breakpad-build-release.aar

    注意:HBuilder X 3.8.7及以上版本新增库install-apk-release.aar,上架谷歌应用市场不能包含此库,更多参考文档

    avatar

    在build.gradle中添加资源引用

    注意:HBuilderX3.2.5版本之后适配了AndroidX。

    AndroidX版本需添加如下资源

    implementation fileTree(include: ['*.jar'], dir: 'libs')
    implementation fileTree(include: ['*.aar'], dir: 'libs')
    implementation 'androidx.appcompat:appcompat:1.0.0'
    implementation 'androidx.legacy:legacy-support-v4:1.0.0'
    implementation 'androidx.recyclerview:recyclerview:1.0.0'
    implementation 'com.facebook.fresco:fresco:2.5.0'
    implementation "com.facebook.fresco:animated-gif:2.5.0"
    implementation 'com.github.bumptech.glide:glide:4.9.0'
    implementation 'com.alibaba:fastjson:1.2.83'
    implementation 'androidx.webkit:webkit:1.3.0'
    

    uni-app配置时需要在build.gradle中添加aaptOptions配置

    aaptOptions {  
        additionalParameters '--auto-add-overlay'  
        ignoreAssetsPattern "!.svn:!.git:.*:!CVS:!thumbs.db:!picasa.ini:!*.scc:*~"  
    }  
    

    注意:更新SDK时需要同时更新aar/jar文件和build.gradle配置

  2. 应用配置

    • 配置Appkey

    3.1.10版本起需要申请 Appkey,申请请参考

    打开Androidmanifest.xml, 导航到Application节点,创建meta-data节点,name为dcloud_appkey,value为申请的AppKey如下:

    <application
        ...>
        <meta-data
            android:name="dcloud_appkey"
            android:value="替换为自己申请的Appkey" />
    

    • 配置应用版本号

    avatar

    versionCode为应用的版本号(整数值),用于各应用市场的升级判断,建议与manifest.json中version -> code值一致

    versionName为应用的版本名称(字符串),在系统应用管理程序中显示的版本号,建议与manifest.json中version -> name值一致。

    applicationId为应用的包名,一般设置为反向域名,不建议修改。

    建议将targetSdkVersion设置为30或以上。

    ** 注意:如果targetSdkVersion设置为34时,需要在build.gradle的android节点下新增以下内容:

    packagingOptions {
    	jniLibs {
    		useLegacyPackaging true
    	}
    }
    

    **

    App离线SDK minSdkVersion最低支持21,小于21在部分5.0以下机型上将无法正常使用。

    完整版build.gradle可参考如下内容。

    apply plugin: 'com.android.application'
    
    android {
    	compileSdkVersion 29
    	defaultConfig {
    		applicationId "com.example.myapplication"
    		minSdkVersion 21
    		targetSdkVersion 30
    		versionCode 1
    		versionName "1.0"
    		multiDexEnabled true
    		ndk {
    			abiFilters 'x86', 'armeabi-v7a', 'arm64-v8a'
    		}
    	}
    	compileOptions {
    		sourceCompatibility JavaVersion.VERSION_1_8
    		targetCompatibility JavaVersion.VERSION_1_8
    	}
    	buildTypes {
    		release {
    			minifyEnabled false
    			proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    		}
    	}
    }
    
    dependencies {
    	implementation fileTree(dir: 'libs', include: ['*.aar', '*.jar'], exclude: [])
    	implementation 'androidx.appcompat:appcompat:1.0.0'
    	implementation 'androidx.legacy:legacy-support-v4:1.0.0'
    	implementation 'com.alibaba:fastjson:1.2.83'
    	implementation 'androidx.webkit:webkit:1.3.0'
    }
    

    注意:如果需要集成的第三方sdk存在so库文件,只需添加armeabi-v7a、arm64-v8a、x86三个文件夹即可,否则会导致在部分手机上无法运行。

    • 配置应用名称

    打开app-> src -> main -> res -> values -> strings.xml文件,修改“app_name”字段值,该值为安装到手机上桌面显示的应用名称,建议与manifest.json中name(基础配置中的应用名称)对应。

    • 配置应用启动页及provider节点

    将下述activity信息添加到Androidmanifest.xml的application节点中

    注意:新建的项目默认会有一个MainActivity的节点,必须删掉!

    注意:为适配折叠屏,需要在PandoraEntryActivity的android:configChanges属性中追加“smallestScreenSize|screenLayout|screenSize”,参考如下配置。

    注意:为适配暗黑模式,需要在PandoraEntryActivity的android:configChanges属性中追加“uiMode”,参考如下配置。

    	<activity
            android:name="io.dcloud.PandoraEntry"
            android:configChanges="orientation|keyboardHidden|keyboard|navigation"
            android:label="@string/app_name"
            android:launchMode="singleTask"
            android:hardwareAccelerated="true"
            android:theme="@style/TranslucentTheme"
            android:screenOrientation="user"
            android:windowSoftInputMode="adjustResize" >
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
            <intent-filter>
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <action android:name="android.intent.action.VIEW" />
                <data android:scheme=" " />
            </intent-filter>
        </activity>
    	<activity
            android:name="io.dcloud.PandoraEntryActivity"
            android:launchMode="singleTask"
            android:configChanges="orientation|keyboardHidden|screenSize|mcc|mnc|fontScale|keyboard|smallestScreenSize|screenLayout|screenSize|uiMode"
            android:hardwareAccelerated="true"
            android:permission="com.miui.securitycenter.permission.AppPermissionsEditor"
            android:screenOrientation="user"
            android:theme="@style/DCloudTheme"
            android:windowSoftInputMode="adjustResize">
        </activity>
    

    添加provider信息到Androidmanifest.xml的application节点中

    注意:3.3.7及以上版本,可以不添加

    <!--provider节点必须添加-->
    <provider
        android:name="io.dcloud.common.util.DCloud_FileProvider"
        android:authorities="${apk.applicationId}.dc.fileprovider"
        android:exported="false"
        android:grantUriPermissions="true">
        <meta-data
            android:name="android.support.FILE_PROVIDER_PATHS"
            android:resource="@xml/dcloud_file_provider" />
    </provider>
    

    注意:${apk.applicationId} 必须替换成当前应用的包名

    如果集成离线SDK时需要重写application,必须继承自DCloudApplication,否则会导致SDK中业务逻辑无法正常运行。

    将对应的application配置到Androidmanifest.xml中(如下),并添加tools:replace="android:name"以防出现冲突。

    	<application  
    	    android:name="io.dcloud.test.TestApplication"  
    	    android:icon="@drawable/icon"  
    	    android:label="@string/app_name"  
    	    tools:replace="android:name">
    	</application>
    

    • 配置应用图标和启动界面

      • 图标名称

        icon.png为应用的图标。

        push.png为推送消息的图标。

        splash.png为应用启动页的图标。

    将icon.png、push.png、splash.png放置到drawable,drawable-ldpi,drawable-mdpi,drawable-hdpi,drawable-xhdpi,drawable-xxhdpi文件夹下,不同文件夹下对应不同图片尺寸,可参考文档

    avatar

    修改Androidmanifest.xml中application节点的icon属性为@drawable/icon。如下图:

    avatar

    注意:splash.png在不同设备上显示效果不一样,为防止出现拉伸的状况,建议使用Android studio生成.9.png类型图片,可参考文档

  3. 资源配置

    Android studio默认项目没有assets文件夹,需手动创建,创建位置与java目录同级。

    • 创建data文件夹并拷贝资源

    将SDK->assets->data文件夹拷贝到刚刚创建的assets文件夹下,如下图:

    avatar

    注意:SDK升级时,data下资源需要同时更新。

    • 创建apps文件夹并拷贝资源

    将HBuilderX中的项目导出,将导出的资源复制到assets->apps下,如下图所示:

    avatar

    导出app资源

    • 修改dcloud_control.xml文件

    修改dcloud_control.xml中的appid为拷贝过来的uni-app的id,确保dcloud_control.xml中的appid与manifest.json中的id与文件夹名一致,如下图所示:

    avatar

    生成自定义基座,需要在根节点下添加debug="true"和syncDebug="true",如下图:

    avatar

    自定义基座支持热更新需要将debug-server-release.aar打入apk中,生成正式包时可以删除。

    详细步骤可参考链接

  4. 如何配置暗黑模式 在AndroidManifest.xml中添加:

    <meta-data
                android:name="DCLOUD_DARK_MODE"
                android:value= "替换为应用的主题模式" />
    

    其中可用的模式分别为 lightdarkauto, 此设置会影响启动时的默认模式,另外在运行时可使用plus.nativeUI.setUIStyle动态修改主题模式。

    注意PandoraEntryActivityandroid:configChanges配置必须包含uiMode。

  5. 其他配置

    AndroidX 配置

    需要在项目根目录下的gradle.properties文件中添加如下内容

    android.useAndroidX=true
    android.enableJetifier=true
    

# uts插件

注意:需要HBuilder X 4.18版本及以上。

如果uni-app项目包括uts原生插件,资源导出之后会在resources目录下新增uni_modules目录。参考:

# 添加uts依赖

  1. utsplugin-release.aar拷贝到项目的libs目录下
  2. 在app项目的build.gradle中添加如下内容
    dependencies {
        implementation "com.squareup.okhttp3:okhttp:3.12.12"
        implementation "androidx.core:core-ktx:1.6.0"
        implementation "org.jetbrains.kotlin:kotlin-stdlib:1.8.10"
        implementation "org.jetbrains.kotlin:kotlin-reflect:1.6.0"
        implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.8"
        implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.8"
        implementation "com.github.getActivity:XXPermissions:18.0"
    }
    

# 配置uts插件

uts原生插件导入参考文档,将uts插件导入到android项目中。

具体示例可以参考离线打包SDK中的UniPlugin-Hello-AS工程。

# 运行

连接手机,点击按钮,运行即可。

avatar