文档

使用 mPaaS 插件

更新时间:

mPaaS 插件通过图形化界面,帮助您快速地接入 mPaaS 并便捷地使用 mPaaS 的功能。

mPaaS 插件的功能主要包括 原生 AAR 方式组件化接入基础工具帮助构建

  • 原生 AAR 接入组件化接入 分别提供了接入面板,在接入面板中的接入向导会协助您将 mPaaS 以不同的接入方式接入到您的工程中。在完成接入后,您还可以在接入面板进行 基线升级组件管理

  • 基础工具 中,mPaaS 提供了 热修复生成加密图片(专有云配置文件)生成 UC Key 签名信息 生成蓝盾图片 的功能,方便快速完成使用 mPaaS 功能前的信息准备。

  • 帮助 中,mPaaS 提供了 日志诊断工具常见问题、和 查看文档 的功能,方便在使用 mPaaS 过程中遇到问题时快速获得支持。

  • 构建,完成接入 mPaaS 后构建工程。

添加配置文件

接入过程的主要工作是将配置文件添加到工程中,mPaaS 插件支持 手动导入 的方式添加配置文件。手动导入需要在控制台下载配置文件后,再通过 mPaaS 插件手动添加到工程里。

手动导入

前提条件

  • 已创建了蚂蚁或阿里云账号并开通了 mPaaS 服务。

  • 已在 mPaaS 控制台创建应用。更多关于创建应用的信息,请参见 在控制台创建 mPaaS 应用

  • 已有一个Android 开发工程。

操作步骤

  1. 在 Android Studio 中打开已有工程,单击 mPaaS > 原生 AAR 接入组件化接入。在弹出的接入面板中,单击 导入 App 配置 下的 开始导入

  2. 选择 我已经从控制台上下载配置文件(Ant-mPaaS-xxxx.config),准备导入到工程,单击 Next

  3. 选择配置文件后,单击 Finish,即完成了配置文件的导入。导入成功后,将会收到导入配置文件成功的提示信息。

AAR 接入

操作步骤

  1. 在 Android Studio 中打开已有工程,单击 mPaaS > 原生 AAR 接入

  2. 导入 App 配置。在接入面板中,单击 开始导入,使用 手动导入 的方式完成配置文件的添加。

后续步骤

  1. 接入/升级基线

  2. 配置/更新组件

组件化接入

操作步骤

  1. 在 Android Studio 中打开已有工程,单击 mPaaS > 组件化接入

  2. 导入 App 配置。在接入面板中,单击 开始导入,使用 手动导入 的方式完成配置文件的添加。

  3. 转换工程。如果您的工程是原生 Android 工程,还需要对工程进行转换。在接入面板中,单击 安装 mPaaS Portal。在安装 mPaaS Portal 窗口中,分别选择原始工程的位置和配置文件,单击 OK

后续步骤

  1. 接入/升级基线

  2. 配置/更新组件

接入/升级基线

升级到常规基线

操作步骤

  1. 单击 mPaaS > 原生 AAR 接入组件化接入,在弹出的接入面板中,单击接入/升级基线下的 开始配置

  2. 选择需要升级的基线版本,单击 OK。 升级成功后,您将看到 基线升级成功 的提示。

后续步骤

单击接入面板中的升级基线,在选择基线窗口中将会看到您的基线版本号。

升级到自定义基线

通常情况下,我们提供的基线面向所有客户,如 10.1.32、10.1.60、10.1.68。当您需要定制 mPaaS 的功能时,您可以向和您对接的 mPaaS 的工作人员提出需求,我们会按照您的需求为您定制基线。在交付时,mPaaS 的工作人员会向您提供定制基线的 ID,您只需要在 mPaaS 插件中填写该 ID,即可获得此定制基线。

前提条件

确认您的 Android Studio mPaaS 版本为 V2.19111217 或以上。您可以参考 更新 mPaaS 插件 以了解当前的 mPaaS 插件版本和如何升级 mPaaS 插件。

操作步骤

  1. 删除您 Android Studio 工程里已经存在的 mpaas_package.json 文件。

  2. 单击 mPaaS > 原生 AAR 接入组件化接入,在弹出的接入面板中,单击接入/升级基线下的 开始配置

  3. 在基线升级对话框中勾选 自定义基线 并输入您得到的定制基线 ID。

  4. 单击 OK,即完成自定义基线的引入。

配置/更新组件

mPaaS组件管理(AAR)

前提条件

您已完成基线升级。

操作步骤

  1. 单击 mPaaS > 原生 AAR 接入,在弹出的接入面板中,单击配置/更新组件下的 开始配置

  2. 在弹出的管理窗口中,单击 mPaaS 组件管理,选择要进行管理的 module,勾选要添加的组件,单击 OK。如果您的工程中有多个 module,您可以在选择不同的 module 后,分别为其添加组件。

  3. 组件添加完成后,单击 OK

组件管理

操作步骤

  1. 单击 mPaaS > 组件化接入,在弹出的接入面板中,单击配置/更新组件下的 开始配置

  2. 在弹出的组件管理窗口中,单击按钮安装需要的组件。

基础工具

基础工具中包含 热修复生成加密图片(专有云配置文件)生成控制台用签名 APK生成 UC Key 签名信息生成蓝盾图片 等功能。

热修复

使用热修复能力前,首先要让 App 具备热修复的能力。更多详情,请参见 热修复管理:接入 Android——热修复

生成热修复补丁

使用 mPaaS 插件的 生成热修复补丁,通过以下步骤生成热修复包:

  1. 针对不同的 mPaaS 集成方式,选择对应的包,通过 mPaaS 插件的 生成热修复补丁 生成热修复包。

    • 如果是 原生 AAR 工程 ,需要准备有 bug 的线上 APK 包和修复后的 APK 包。mPaaS 插件会根据代码的不同,生成热修复包。

      提示:

      • New bundle 栏,填写修复后的 APK 包的本地地址。

      • Old bundle 栏, 填写有 bug 的 APK 包的本地地址。

      • 白名单 一栏输入白名单。

    • 如果是 组件化(Portal&Bundle)工程,需要准备 正在使用的有 bug 的 bundle 包修复后的 bundle 包

      提示:

      • bundle 的输出路径为 bundle 的主 module 目录下的 build/intermediates/bundle/xxxx-raw.jar。如果是 release 包则没有 -raw

      • New bundle:选择修复 bug 的包路径。

      • Old bundle:选择有 bug 的包路径。

      • 白名单:选择用于指定修复的类的 .txt 格式的配置文件。该配置文件的编写规则见下文 白名单配置文件编写规则。 使用原生 AAR 工程时强烈推荐使用该功能。

      • Patch file dir:输出的 patch 包路径。

      • 是否使用 dexPatch:选择是否使用 dexPatch 热修复方式。mPaaS 插件的 生成热修复补丁 功能支持 Andfix 和 dexPatch 两种热修复方式。不论使用哪种热修复方案,在发版本前都需要进行验证,查看热修复包是否能生效。

        • 不勾选时,会生成 Andfix 热修复包。Andfix 热修复包能够立即生效,不需要重启应用;但因机型问题,修复的场景限制较多。

        • 勾选时,会生成 dexPatch 热修复包。dexPatch 热修复包不能立即生效,需要杀掉进程后才能生效;但其能够修复的场景比 Andfix 热修复包多,且机型适配问题少。

  2. 输入签名信息生成热修复包。

    重要

    生成热修复包所需要的签名文件必须和运行的 APK 的签名文件保持一致,并且签名文件和生成图片选择的 APK 的签名文件也要保持一致。生成的图片需要放在 Portal 工程的 res/drawable 文件夹下面,命名为 yw_1222.jpg

白名单配置文件编写规则

打热修复包时用于指定修复的类的配置文件为 .txt 格式,该配置文件应包含并按顺序包含以下信息:

  1. 需要 Patch 的类。以 L 开头,后跟以混淆后真实类名。如果多个类,每行只可写一个。示例:Lxxx.xxx.clazzX

  2. 设置 Patch 类型为 dexpatch。示例:PatchType: dexpatch

  3. 设置是否是静态 Bundle。默认为 true。示例:HostDex: true

  4. 适配 Android 11。示例:android-phone-mobilesdk-quinox-Configs: ForceEnableQSecondDex-trueandroid-phone-mobilesdk-quinox 为 Bundle 名称。如果采用的是组件化 Portal&Bundle 接入方式,请按照 Bundle 名称更新; AAR 接入方式下没有 Bundle 工程,值就是 android-phone-mobilesdk-quinox

合并补丁

一个 Android App 版本最多只能有一个热修复包在运行。如果客户端某版本有两个 bug,那需要先在本地使用 合并补丁 功能将修正两个 bug 的热修复包合成一个热修复包。例如,针对某一个版本的 App 已经发过热修复包 A, 之后在这个版本上又发现了另外一个问题,这时可在本地生成另外一个热修复包 B,然后合并 A 与 B 两个热修复包,最后下发到客户端。

说明

本节仅针对使用组件化(Portal&Bundle)工程的用户,使用原生 AAR 工程的用户可以在原先修复的基础上,相对于最原始未修复的包再打出一个补丁发布。

操作步骤
  1. 填写热修复包文件夹地址。

    • Merge dir:选择合并的 hotpatch 包目录。文件夹下面是所有的需要合并的包,包名需要以 .jar 或者 .apk 结尾。

    • Patch file dir:选择合并之后输出的热修复包目录。

  2. 配置签名信息。

合并完成后,将会收到合并成功的提醒。

生成加密图片(专有云配置文件)

为了安全,mPaaS 某些组件访问网络时需要对内容进行加密。

  • 具有特殊名称 yw_1222.jpg 的图片为加解密提供密钥信息。mPaaS 组件自动使用该图片进行加解密,无需额外操作。

  • 由于公有云环境已弃用该加密图片,故公有云用户可忽略本节内容。

生成并使用加密图片 yw_1222.jpg 的详情如下。

准备

加密图片与 APK 的签名文件有绑定关系。因此,需要准备 Portal 工程签名之后的 APK。具体的签名步骤,请参考 Android 官方网站:对应用进行签名

说明
  • 此处的 APK 应和 发布版本 的 APK 使用相同的签名文件。

  • 生成的加密图片只能用在该 APK 工程中。

生成

您可以通过 mPaaS 插件 生成加密图片。

  1. 在 Android Studio 中,单击 mPaaS > 基础工具 > 生成加密图片(专有云配置文件)

  2. Release Apk, 选择 Portal 工程签名之后的 APK 文件, RSA 会自动填充。

  3. mPaaS Config File, 选择 Portal 工程的 .config 文件, workSpaceIdappIdpackageName 会自动填充。如果没有,可以根据工程的 .config 文件中的配置填写到对应输入框中。

  4. 填写 appsecret

    注意:作为服务端管理人员,您可以从控制台中查询 appid 所对应的 appsecret

  5. jpg Version 栏,填写对应的无线保镖图片版本号。

    说明

    查看 Portal 工程主 module 下 build.gradle 文件中 securityguard 版本,低于 5.4 的填 4(例如基线中给出的 securityguard-build:5.1.38.180402194514),其余填 5

  6. outPath, 选择无线保镖图片 yw_1222.jpg 的输出路径,即加密图片生成的本地路径。

  7. 单击 OK 生成加密图片。

使用

加密图片的使用步骤如下:

  1. 将加密图片 yw_1222.jpg 存放到 Portal 工程的 res/drawable 文件夹中。

  2. 如使用 ProGuard,需避免加密图片被混淆。

    1. 检查 build.gradle 中是否配置了如下内容:

      minifyEnabled true
      shrinkResources true
    2. 若有如上配置,为了避免加密图片被混淆,需要在 res/raw 下创建 keep.xml 文件。文件内容如下:

      <?xml version="1.0" encoding="utf-8"?>
      <resources xmlns:tools="http://schemas.android.com/tools"
      tools:keep="@drawable/yw_1222*" /><!--tools:discard="@layout/unused2"-->

生成蓝盾图片

如果您从 mPaaS 控制台下载的 .config 文件中的 absBase64Code 值为空,则需进行下面 生成蓝盾图片 的操作(适用于私有云场景)。

重要

如果您在公有云环境下,从 mPaaS 控制台下载的 .config 文件中的 absBase64Code 值为空,请确认下载前已上传签名正确的 APK 并重新下载。详情请参考 填写配置信息,并上传签名 APK

单击 mPaaS > 基础工具 > 生成蓝盾加密图片,输入相关信息,即可生成蓝盾图片。

重点输入项说明:

  • Release Apk : 接入 mPaaS 的工程打包出的 release apk 包,需要进行签名。

  • MD5: release apk 包上传之后会自动获取填入,即 apk 包的 public md5 key

  • mPaaS config File: mPaaS 控制台点击下载配置即可下 .config 文件并传入。

  • appSecret:mPaaS 控制台查看。

  • 其他项 appId、packageName、outPath 传入以上信息后会自动识别填入。

最后将生成的图片添加到工程的 assets 目录下。

生成控制台用签名 APK

在 mPaaS 控制台中获取配置文件时,需要上传签名后的 APK 文件。但在未创建工程或未编译出签名后的 APK 时,获取配置文件的过程就会受阻而无法进行。为解决此问题,mPaaS 已将此过程简化为 Android Studio mPaaS 插件的 生成控制台用签名 APK 功能。该功能可在只需输入签名相关的参数的前提下,生成签名后的 APK。

生成

  1. 单击 mPaaS > 基础工具 > 生成控制台用签名 APK,进入 构造签名 APK 页面。

  2. 构造签名 APK 页面,填写相关配置信息。

  3. 单击 OK 即可生成签名后的 APK 文件。

  4. 单击 Reveal in Finder 即可找到上述步骤生成的 APK 文件,文件名为 mpaas-signed.apk。至此,签名后的 APK 生成成功。

    打开该 APK 文件查看,会发现该文件很小,且已经被签名。

生成 UC Key 签名信息

在 Android 应用中接入 UC SDK 能够有效解决各种厂商浏览器的兼容性问题。为添加 UC SDK,您需要先申请 UC SDK 的授权。该功能能够帮助您快速获得授权,下文介绍了申请 UC SDK 授权的全流程操作。

说明

该功能自 V2.20062211 版本起加入。更多信息,请参见 V2.20062211 发布说明

操作步骤

  1. 在工程中,添加 UC 内核(UCCORE) 依赖。

  2. 提供应用的 Android native package 名称(package name)。

  3. 单击 mPaaS > 基础工具 > 生成 UC Key 签名信息,进入 查询签名信息 页面。

  4. 查询签名信息 页面,填写相关配置信息。单击 Next

  5. 复制获得的 SHA1 信息。

  6. 填写 UC key 申请表 并提交。

    说明

    由于产品策略变更,UC 不再全面开放申请,从2022.12.01起不支持公开申请 UC Key。需要填写表单相关信息,工作人员会进行审核并反馈申请结果。

  7. 将获取的 Key 填入 Portal 项目的 AndroidManifest.xml 文件中:<meta-data android:name="UCSDKAppKey" android:value="您申请获得的 key"/>

    说明

    UC SDK 的授权信息与 APK 的 包名 以及 签名 绑定。因此,如果 UCWebView 没有生效,请检查签名和包名与申请时使用的信息是否一致。

帮助

日志诊断工具

  1. 单击 mPaaS > 帮助 > 日志诊断工具

  2. 将您需要分析的日志信息 copy 到输入框,单击 Next

  3. 等待分析结果。

  4. 查看分析结果。 分析结果中包含定位原因解决方案 的信息,您可以根据具体的定位信息和解决方案来修改您的代码。

  5. 修改完成后单击 Finish 关闭弹窗。

常见问题

单击 mPaaS > 帮助 > 常见问题,即可跳转至 接入 Android 常见问题,查看接入过程中的常见问题。

查看文档

单击 mPaaS > 帮助 > 查看文档,即可跳转至 mPaaS 文档中心,查看各组件的使用文档。

构建

在 Android Studio 中选择 mPaaS > 构建。即可构造工程。