文档

使用 mPaaS Xcode Extension

更新时间:

本文将对 mPaaS Xcode Extension 的使用进行详细介绍,主要包括以下方面:

启动 mPaaS Xcode Extension

在 macOS 的 应用程序 中找到 mPaaS 独立的应用 mPaaSPlugin,单击直接运行即可。

新建工程

创建一个全新的、基于 mPaaS 框架的工程,所需步骤如下。

  1. 单击 mPaaS > 创建工程

  2. 配置 mPaaS 新工程,输入 项目名称 并导入下载的 .config 配置文件,然后单击 下一步 按钮。 导入配置文件

  3. 选择要创建应用的 模板类型,然后单击 下一步 按钮。 选择模板类型

  4. 选择工程使用的 基线类型和版本,然后单击 下一步 按钮。 baseline-version

    基线类型说明:

    • 标准基线:公开的标准 mPaaS SDK 版本,可以在下拉列表中选择。 标准基线

    • 定制基线:目前只开放给专有云用户,在输入框中填入对应的基线 ID 后会自动进行校验。校验失败会提示错误信息。校验正确后即可使用。定制基线

  5. 选择工程需要添加的模块,然后单击 下一步 按钮。

    说明

    您也可以先不添加模块,在创建工程之后,再参考各组件的接入文档,使用 编辑工程 功能添加所需的模块。

    添加模块

  6. 选择项目保存的目录,单击 创建 按钮。 创建工程-选择文件夹

  7. 开始创建工程,创建成功之后会自动打开新建的 Xcode 工程。 创建工程

编辑工程

打开工程

如果您已经有 Xcode 工程,那您也可以通过插件直接打开现有工程。将工程文件拖拽进插件、或者单击插件后定位到工程文件即可。打开工程

工程面板介绍

单击 mPaaS > 编辑工程,打开编辑工程页面,页面分为若干区域,如下图所示。

image.png

  • 1 菜单栏:展示所有工程的操作菜单。

  • 2 工具栏:展示常用的工具和当前操作的 target 信息。

  • 3 状态栏:展示当前编辑的工程路径。

  • 4 工程结构栏:展示工程的结构,包括 workspace、project、target 的结构。

  • 5 工作区:主要的操作区域,根据选择不同的编辑菜单展示不同。

  • 6 隐藏键:可以展开/隐藏工程结构侧边栏。

  • 7 切换工程:打开另一个工程进行编辑。

  • 8 展示:在 Finder 中展示当前工程。

  • 9 关闭:关闭当前编辑中的工程。

导入云端元数据

单击 导入云端元数据 菜单,单击 选择配置文件 按钮,选择下载的云端数据配置文件,页面中可以预览该配置文件的基础信息,单击 开始导入 按钮,将对应的配置导入到当前工程中。

说明

选择配置文件之后,可以单击 “X” 按钮来关闭,只有单击 开始导入 之后配置才会生效。

导入云端元数据

工程概览

单击 工程概览 菜单,工作区会解析工程配置,展示工程的详细信息,包括工程基础信息,mPaaS 基线信息,工程状态,应用信息。相关操作包括:

  • 模块查看:单击 展开 按钮,弹框展示集成的所有模块。

  • 工程状态:

    • 未知:表示未集成 mPaaS 或者解析信息失败。

    • 未安装:表示 mPaaS 库文件缺失,不可正常运行,单击 安装 按钮可以完成安装操作。

    • 已安装:表示 mPaaS 库文件已经正确安装,工程可以直接运行。

工程概览

编辑模块

单击 编辑模块 菜单,工作区会根据工程属性展示不同的页面。

已经集成 mPaaS 的工程

  1. 编辑已经集成 mPaaS 的工程,工作区会展示工程中已经集成的模块列表。 edit project

  2. 单击 修改模块 会弹出 模块列表 编辑页面。

    • 在列表中单击模块卡片来添加或取消模块。select-cancel

    • 单击每个模块右侧的 详情 按钮可以查看该模块的具体信息,包括描述、Release Note、包含的 framework 文件详情等。detail

    • 单击左上角的 X 可以关闭模块列表,返回到主页面,选择的结果不会生效。

    • 单击右上角的 保存 按钮保存编辑结果,同时返回到主页面,工作区的模块列表中会展示编辑的结果。result

  3. 返回主页面后,单击 开始编辑,将修改的模块添加到当前工程中或从当前工程中移除。

    说明

    只有单击开始编辑之后,结果才会生效。

原生系统工程

  1. 编辑原生的系统工程,工作区会展示未集成的提示页面。 edit

  2. 单击 添加模块 会弹出 模块列表 编辑页面。

    1. 进入页面会提示选择集成的 基线类型和版本,选择好基线后,单击 确认 按钮会收起基线选择菜单,下方刷新出对应基线的模块列表。select-version

    2. 进入模块列表后,单击右上方的 选择基线 下拉菜单可以重新选取基线版本,切换基线后,之前添加的结果会丢失。model

    • 在列表中单击模块卡片来添加模块。select-cancel1

    • 单击每个模块右侧的 详情 按钮可以查看该模块的具体信息,包括描述、Release Note、包含的 framework 文件详情等。details

    • 单击左上角的 X 可以关闭模块列表,返回到主页面,选择的结果不会生效。

    • 单击右上角的 保存 按钮保存编辑结果,同时返回到主页面,工作区的模块列表中会展示编辑的结果。result1

  3. 返回主页面后,单击 开始编辑,将修改的模块添加到当前工程中或从当前工程中移除。

    说明

    只有单击开始编辑之后,结果才会生效。

编辑模块的相关操作及说明

  • 选择基线

    • 标准基线:公开的标准 mPaaS SDK 版本,可以在下拉列表中选择。 标准基线

    • 定制基线:目前只开放给专有云用户,在输入框中填入对应的基线 ID 后会自动进行校验。校验失败会提示错误信息。校验正确后即可使用。定制基线

  • 修改模块:打开模块列表,进行模块的添加或删除操作。

  • COPY建议启用该项。选中该项后,依赖的 SDK 文件会自动拷贝到工程目录下。

  • 版本:在工作区会展示当前工程集成 mPaaS SDK 的版本信息。

  • 开始编辑:执行模块编辑操作。

更新产品集

选择 更新产品集 后,单击 开始更新 按钮执行升级,集成的 mPaaS SDK 产品集会更新到最新的版本。

update

在工作区会展示当前工程的产品集信息和基线所在的最新产品集信息,单击 查看模块更新详情 按钮,会弹出模块列表页面,可以查看每个模块的更新状态。查看模块更新详情

单击每个模块右侧的 详情 按钮,可以查看该模块的具体信息,包括描述、Release Note、包含的 framework 文件详情等。查看模块详情

如果当前工程未集成 mPaaS,展示提示页面,建议先在 编辑模块 进行集成。not-integrated

更新产品集的相关操作及解释如下:

  • 当前产品集版本:已集成产品集会展示当前的产品集版本,如果工程未集成产品集,右上角展示当前的基线版本。

  • 最新产品集版本:展示最新产品集的版本号,版本号结构为“基线版本+产品集版本”,如 10.1.60-beta (20)。

  • 模块更新数量提示:提示当前工程集成的模块在最新产品集中更新的数量。

  • 查看模块更新详情:弹出模块列表页面,可以查看每个模块的更新状态。

  • 查看 Release Note:打开文档“SDK 发布说明”。

  • 产品集更新时间:展示最新产品集的发布时间。

  • 开始升级:执行升级操作。

升级基线

单击 升级基线 菜单,单击 确认升级 按钮可进行升级。upgrade

在基线选择框内选择基线的类型和版本,下方会出现对应基线的预览框,单击预览中的 查看包含的模块详情 按钮,会弹出模块列表页面,展示当前所选基线的模块列表和模块的安装情况。status

单击每个模块右侧的 详情 按钮,可以查看该模块的具体信息,包括描述、Release Note、包含的 framework 文件详情等。详情

如果当前工程未集成 mPaaS,展示提示页面,建议先在 “编辑模块” 进行集成。升级基线

升级基线的相关操作及解释如下:

  • 选择基线

    • 定制基线:目前只开放给专有云用户,在输入框中填入对应的基线 ID 后会自动进行校验。校验失败会提示错误信息。校验正确后即可使用。定制基线

    • 标准基线:公开的标准 mPaaS SDK 版本,可以在下拉列表中选择。 标准基线

  • 预览:展示基线的基线类型和版本,单击“查看包含的模块详情”可以查看对应的模块列表信息。

  • 确认升级:执行升级基线操作。

升级基线之后工程中的 mPaaS 信息将会全部更新,当从 低于 10.1.32 的版本升级到 10.1.32 及以上版本 时,工程中的 MPaaS 目录结构和 Info.plist 中的内容会发生一些变化,具体内容如下。

目录结构变化

升级前工程中 MPaaS 目录下存在的组件 category 目录和文件,在升级之后只会保留 APMobileFramework 和 mPaas,其他目录将会移除自动移除,比如 MPHotpatchSDK、APRemoteLogging 等。如果这些目录下有存放自定义的文件,请提前备份保存。详细目录结构参见 mPaaS 目录结构

Info.plist 变化

升级前工程中 Info.plist 中插入的 mPaaS 相关字段内容如下图所示。Info.plist 变化

由于 10.1.32 及以上的版本只需保留 Product Version, 不再需要 Product ID、mPaaS、mPaaSInternal 字段,所以升级基线后,插件会自动将这些字段移除。如果发现未成功移除,需手动删除这些内容。升级后的内容如下图所示:

说明

手动删除时,请勿删除 Product Version

升级后的内容

无线保镖

单击 无线保镖 菜单,在页面中输入 AppSecret 等信息,单击 生成图片 按钮可生成 RPC 验签和离线包等解密需要的 yw_1222.jpg 图片。无线保镖无线保镖的相关操作及解释如下:

  • 默认路径:该路径展示为工程中无线保镖图片的默认存放位置。

  • App Secret:无线保镖验签的私钥。公有云用户可以在 mPaaS 控制台查询;专有云用户请向服务端开发人员咨询。单击右侧帮助按钮可以查看更多信息。

  • Type:无线保镖图片 yw_1222.jpg 的类型。

    • 标准:生成普通的无线保镖图片(默认为此类型)。

    • 账户通:生成小程序账户通专用的图片。

      注意:使用该类型的无线保镖图片后,注意对账户通和网关相关功能进行回归测试)。

  • JPG Version:无线保镖图片 yw_1222.jpg 的版本号。根据客户端 SecurityGuardSDK.framework 的版本号区分:

    • 若版本号低于 5.3.85,则 yw_1222.jpg 版本号为 V4。

    • 若版本号高于或等于 5.3.85,则 yw_1222.jpg 版本号为 V5。无线保镖2

  • 生成图片:单击按钮会提示选择图片保存的路径,自动打开默认路径,选择路径后会执行生成无线保镖图片操作。

    说明
    • 公有云用户导入的 meta.config 文件中已生成了此图片,如无特殊需求,一般不用重新生成。

    • 专有云用户请使用此方法生成 yw_1222.jpg 图片,并添加到工程中。

    生成图片

自定义快捷键

mPaaS Xcode Extension 支持用户为 mPaaS 菜单添加自定义快捷键,方便快捷并且个性十足。打开 Xcode 偏好设置,选择 Key Binding,过滤 mPaaS 即可设置,如下图所示。自定义快捷键

基础工具

单击 mPaaS > 基础工具,打开基础工具页面,如下图所示。mPaaS 提供了一些基础工具供开发者使用,包括自助服务、热修复工具、和打包构建工具。基础工具

自助服务-日志诊断工具

使用日志诊断工具,可以方便自助排查 mPaaS SDK 使用中的问题,输入问题日志,该工具会自动扫描匹配到的问题原因,并提供解决方案。

单击 日志诊断工具 图标,打开诊断工具页面。在输入框中输入问题日志,单击 提交 按钮可以自动对日志进行分析。

日志诊断工具

分析到结果之后会弹出诊断报告页面,查看匹配到的问题详情。日志诊断工具

日志诊断工具的相关操作和说明

  • 日志输入框:输入待扫描的原始日志(目前支持客户端运行时的日志)。

  • 重置:提交任务后,如需再次查询,可以单击 重置 在输入框内重新提交日志。

  • 查看完整诊断报告:打开诊断报告窗口,展示当前日志的扫描结果。

热修复生成资源包

使用热修复功能时,为了保障安全性,本地测试通过后的 .js 脚本文件,需要进行打包加密后才能提交到发布平台。

单击 生成资源包 图标,打开生成热修复资源包页面,选择本地测试通过的 .js 脚本和 RSA 密钥文件,填入应用的 App Secret,单击 确定 按钮可以生成加密后的热修复资源包文件。生成资源包

生成资源包的相关操作及解释如下:

  • 脚本文件:本地测试验证通过后的 .js 脚本。

  • App Secret: 应用对应的 App Secret。单击右侧帮助按钮查看更多信息。

  • 私钥文件:已有的 RSA 私钥文件,通过 openssl 获取,与添加到工程中的公钥文件配对的私钥文件。

  • 生成新的 RSA 密钥:如果您还没有密钥文件或者想使用新的密钥文件,可以选中该项,插件会自动帮你生成新的 RSA 密钥对,保存在输出的目录中。

  • 查看产物说明:单击可以展开具体的说明信息,如图中所示。

热修复提取公钥签名

在热修复脚本的验签和加解密这个过程中,涉及到一对 RSA 非对称密钥和一个 AES 对称加密密钥,每个接入应用需要使用自己的密钥,保证脚本下发的安全性。其中验证 RSA 的密钥过程需要在 main.m 中验证公钥自身的签名,以确保公钥文件未被替换。

单击 提取公钥签名 图标,打开提取热修复公钥签名页面,选择生成热修复包使用的公钥和私钥文件,单击 确定 按钮在页面上可以看到提取出来的签名数组。将打印出来的签名数组拷贝到 main.m 方法中即可。提取公钥签名

提取公钥签名的相关操作及解释如下:

  • 公钥文件:生成热修复资源包使用的 RSA 公钥文件。

  • 私钥文件:生成热修复资源包使用的 RSA 私钥文件。

  • 签名数组:展示提取出来的公钥签名。

应用打包

mPaaS 插件提供一键打包功能,输入 bundleID 、bundle version、签名参数等信息,可生成一个 .ipa 的安装包,使用 mPaaS 发布管理进行 App 的升级,提醒用户安装新版本。

单击 应用打包 图标,打开应用打包页面,填写页面全部信息,单击 开始构建 按钮开始打包。应用打包

应用打包的相关操作及解释如下:

  • 工程地址:选择打包工程的目录地址,即工程文件(.xcodeproj.xcworkspace)所在的目录。

  • Scheme:构建的 target 名称。

  • Bundle Identifier:当前工程的 Bundle Identifier 。如果添加了移动网关服务,必须保证与云端元数据中的 bundleId 字段保持一致,否则移动网关验签失败。

  • Build Version:当前工程的版本号。一般与工程里 info.plist 文件中的 Bundle Version 保持一致。

  • CodeSign Identity:签名的证书名称。可在 Keychain 中导入给当前工程签名的证书,找到证书的常用名称即可。

  • Provisioning Profile:与 Bundle Identifier 和签名证书相匹配的 provision 配置文件;

  • Configuration:打包的配置,Debug 或 Release。

  • Build For App Store:是否为 App store 安装包,勾选后表示生成的 .ipa 为上传 App Store 的包;未勾选表示生成的 .ipa 为开发包。

  • 开始构建:单击按钮会提示选择打包产物生成的目录,选择后会开始打包构建操作,打包成功后会自动打开生成的目录文件。

重签名

mPaaS 插件提供对原有 .ipa 安装包重签名的功能,可生成一个重签名后的 .ipa 安装包,可在更多的设备上安装使用,便于测试验证。

单击 重签名 图标,打开重签名页面,填写页面全部信息,单击 确定 按钮开始重签名操作。

重签名

重签名的相关操作及解释如下:

  • IPA 安装包:已有的 .ipa 安装包文件。

  • 证书名称:新证书的名称,可使用 security find-identity -p codesigning -v ~/Library/Keychains/login.keychain查看。

  • 证书 ID:新证书的 ID,可查看 keychain 中相应证书的用户 ID。

  • Provision File:更新证书相匹配的 provision 配置文件。

  • 确定:单击按钮会提示选择重签名文件的保存目录,选择后会开始重签名操作,重签名成功后会自动打开生成的目录文件。

常见问题

在常见问题页面,单击 开始浏览,即可打开详情页面,可以根据查询的具体组件,查看相关的常见问题。

Preferences 设置

打开 mPaaS Xcode Extension 之后,可以单击菜单 mPaaSPlugin > Preferences,或通过快捷键“⌘ + ,” ,打开设置窗口。

Preferences

通用

配置诊断日志保存路径:使用诊断功能时,生成日志报告的保存路径,下拉菜单中选择 Custom 选项,可以自定义日志存储目录。

log path

网络

配置 SOCKS 代理:勾选 启用 SOCKS 代理 来启用代理,同时在下方输入框输入代理服务器的地址和端口。

network

评分及评论

打开 mPaaS Xcode Extension 之后,可以单击首页左下角的 徽章 图标打开 评分及评论 窗口。

修改3.jpg

如果是直接在 应用程序 中启动的 mPaaS Xcode Extension,还可以通过菜单 Help > 撰写评论 打开 评分及评论 窗口。

评论

提交评分及评论

在对话框中单击星形进行评分,填写评论标题和内容,单击 提交 按钮提交评分及评论内容。

说明

已经提交的评论和评分可以再次修改、重新提交。

查看全部评论

在对话框中单击 查看全部评论 按钮,打开新窗口,展示全部用户的评论数据。