快速开始_接入 iOS_小程序_移动开发平台 mPaaS

说明：小程序只在 10.1.60 及以上版本基线中提供支持。

前置条件

您已经接入工程到 mPaaS。更多信息，请参见以下内容：

添加 SDK

根据您采用的接入方式，请选择相应的添加方式。

使用 mPaaS Xcode Extension。
此方式适用于采用了 基于 mPaaS 框架接入 或 基于已有工程且使用 mPaaS 插件接入 的接入方式。
1. 点击 Xcode 菜单项 Editor > mPaaS > 编辑工程，打开编辑工程页面。
2. 选择 小程序，保存后点击 开始编辑，即可完成添加。
使用 cocoapods-mPaaS 插件。
此方式适用于采用了 基于已有工程且使用 CocoaPods 接入 的接入方式。
1. 在 Podfile 文件中，使用 mPaaS_pod "mPaaS_TinyApp" 添加小程序组件依赖。
2. 在命令行中执行 pod install 即可完成接入。

如在接入小程序的过程中遇到问题，欢迎扫码入群讨论。

使用 SDK

本文将结合小程序官方 Demo 来介绍小程序的使用。

小程序的整个使用过程主要分为以下三步：

初始化配置
发布小程序
启动小程序

1. 初始化配置

在配置工程时，您需要：

初始化容器
配置小程序

如果您的 App 生命周期并没有交给 mPaaS 框架托管，您还需进行非框架托管配置（若版本 ≥ 10.1.68.25，推荐使用 10.1.68.25 及以上版本非框架托管配置）。

1.1 初始化容器

容器初始化操作包括启动容器、定制容器和更新小程序包。

1.1.1 启动容器

为了使用 Nebula 容器，您需要在程序启动完成后调用 SDK 接口，对容器进行初始化。必须在 DTFrameworkInterface 的 - (void)application:(UIApplication *)application beforeDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions 中进行初始化。
```
- (void)application:(UIApplication *)application beforeDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // 初始化容器
    [MPNebulaAdapterInterface initNebula];
}
```

若您需要使用 预置小程序包、自定义 JSAPI 和 Plugin 等功能，请将上方代码中的 initNebula 替换为下方代码中的 initNebulaWith 接口，传入对应参数对容器进行初始化。

presetApplistPath：自定义的预置小程序包的包信息路径。
appPackagePath：自定义的预置小程序包的包路径。

pluginsJsapisPath：自定义 JSAPI 和 Plugin 文件的存储路径。

  - (void)application:(UIApplication *)application beforeDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions
  {
      // 初始化容器
      NSString *presetApplistPath = [[NSBundle mainBundle] pathForResource:[NSString stringWithFormat:@"MPCustomPresetApps.bundle/h5_json.json"] ofType:nil];
      NSString *appPackagePath = [[NSBundle mainBundle] pathForResource:[NSString stringWithFormat:@"MPCustomPresetApps.bundle"] ofType:nil];
      NSString *pluginsJsapisPath = [[NSBundle mainBundle] pathForResource:[NSString stringWithFormat:@"Poseidon-UserDefine-Extra-Config.plist"] ofType:nil];
      [MPNebulaAdapterInterface initNebulaWithCustomPresetApplistPath:presetApplistPath customPresetAppPackagePath:appPackagePath customPluginsJsapisPath:pluginsJsapisPath];
  }

说明：initNebula 和 initNebulaWithCustomPresetApplistPath 是两个并列的方法，不要同时调用。

配置小程序包请求时间间隔：mPaaS 支持配置小程序包的请求时间间隔，可全局配置或单个配置。
- 全局配置：您可以在初始化容器时通过如下代码设置⼩程序包的更新频率。
```
[MPNebulaAdapterInterface shareInstance].nebulaUpdateReqRate = 7200;
```
  其中 7200 是设置全局更新间隔的值，7200 为默认值，代表间隔时长，单位为秒，您可修改此值来设置您的全局小程序包请求间隔，范围为 0 ~ 86400 秒（即 0 ~ 24 小时，0 代表无请求间隔限制）。
- 单个配置：即只对当前小程序包配置。可在控制台中前往 新增小程序包 > 扩展信息 中填入 {"asyncReqRate":"1800"} 来设置请求时间间隔。详情参见创建小程序包中的 扩展信息。

1.1.2 定制容器

如有需要，您可以通过设置 MPNebulaAdapterInterface 的属性值来定制容器配置。必须在 DTFrameworkInterface 的 - (void)application:(UIApplication *)application afterDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions 中设置，否则会被容器默认配置覆盖。

  - (void)application:(UIApplication *)application afterDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions
  {
      // 定制容器
      [MPNebulaAdapterInterface shareInstance].nebulaVeiwControllerClass = [MPH5WebViewController class];
      [MPNebulaAdapterInterface shareInstance].nebulaNeedVerify = NO;
      [MPNebulaAdapterInterface shareInstance].nebulaUserAgent = @"mPaaS/Portal";
  }

属性含义如下：

名称	含义	备注
nebulaVeiwControllerClass	H5 页面的基类	默认为 H5WebViewController。若需指定所有 H5 页面的基类，可直接设置此接口。注意：基类必须继承自 H5WebViewController。
nebulaWebViewClass	设置 WebView 的基类	基线版本大于 10.1.60 时，默认为 H5WKWebView。自定义的 WebView 必须继承 H5WKWebView。基线版本等于 10.1.60 时，不支持自定义。
nebulaUseWKArbitrary	设置是否使用 WKWebView 加载小程序包页面	基线版本大于 10.1.60 时，默认为 YES。基线版本等于 10.1.60 时，默认为 NO。
nebulaUserAgent	设置应用的 UserAgent	设置的 UserAgent 会作为后缀添加到容器默认的 UA 上。
nebulaNeedVerify	是否验签，默认为 YES	若配置小程序包时未上传私钥文件，此值需设为 NO，否则小程序包加载失败。
nebulaPublicKeyPath	小程序包验签的公钥	与配置小程序包时上传的私钥对应的公钥。
nebulaCommonResourceAppList	公共资源包的 appId 列表	-
errorHtmlPath	当 H5 页面加载失败时展示的 HTML 错误页路径	默认读取 `MPNebulaAdapter.bundle/error.html`。
configDelegate	设置自定义开关 delegate	提供全局修改容器默认开关值的能力。

1.1.3 更新小程序包

启动完成后，全量请求所有小程序包信息，检查服务端是否有更新包。为了不影响应用启动速度，建议在 (void)application:(UIApplication \*)application afterDidFinishLaunchingWithOptions:(NSDictionary \*)launchOptions 之后调用。

- (void)application:(UIApplication *)application afterDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // 定制容器
    [MPNebulaAdapterInterface shareInstance].nebulaVeiwControllerClass = [MPH5WebViewController class];
    [MPNebulaAdapterInterface shareInstance].nebulaNeedVerify = NO;
    [MPNebulaAdapterInterface shareInstance].nebulaUserAgent = @"mPaaS/Portal";
    [MPNebulaAdapterInterface shareInstance].nebulaCommonResourceAppList = @[@"77777777"];
    // 全量更新小程序包
    [[MPNebulaAdapterInterface shareInstance] requestAllNebulaApps:^(NSDictionary *data, NSError *error) {
        NSLog(@"");
    }];
}

初始化完成后，效果如下：

1.2 配置小程序

1.2.1 配置权限

在 info.plist 中配置以下 App 权限：

NSBluetoothAlwaysUsageDescription：蓝牙权限（iOS 13 中的新增权限）。
NSCameraUsageDescription：相机权限。
NSPhotoLibraryUsageDescription：相册权限。
NSLocationWhenInUseUsageDescription：定位权限。

1.2.2 配置动态库

在当前工程 TARGETS 的 General > Embedded Binaries 中添加 FalconLooks 库。

说明：

配置动态库在 10.1.68.15（含）及以上版本基线中已经取消，无需配置。
您可在 Xcode Extension 中点击 mPaaS > 编辑工程 > 编辑模块，在 工程模块信息 右侧查看基线版本号。

1.3 非框架托管配置

若您 App 的生命周期并没有交给 mPaaS 框架托管，而是指定为您自己定义的 delegate，那么您还需额外配置进行非框架托管。

说明：若您使用的基线版本 ≥ 10.1.68.25，推荐使用下方的非框架托管配置（10.1.68.25 及以上版本）。

1.3.1 启动 mPaaS 框架

在当前应用的 didFinishLaunchingWithOptions 方法中调用 [[DTFrameworkInterface sharedInstance] manualInitMpaasFrameworkWithApplication:application launchOptions:launchOptions]; 来启动 mPaaS 框架。

说明：启动框架必须在当前应用 window 和 navigationController 初始化完成后调用，否则无法生效。

1.3.2 创建应用启动器

创建 DTBootLoader 的子类，重写 createWindow 和 createNavigationController 方法，返回当前应用自己的 window 和 navigationControlle。

设置 window：当前应用的 keyWindow。
设置 navigationController：加载小程序所在的 navigationController，必须继承 DFNavigationController。
- 若当前应用 keyWindow 的 rootviewcontroller 是一个 navigationController，设置为该类即可；
- 若当前应用 keyWindow 的 rootviewcontroller 是一个 tabBarViewController，取加载小程序所在标签（tab）的 navigationController。

在 DTBootPhase 的 category 中重写 setupNavigationController 方法，指定小程序加载的 navigationController。

1.3.3 指定应用启动器

在 DTFrameworkInterface 的 category 中重写方法，指定当前应用自己的 bootloader，并隐藏 mPaaS 框架默认的 window 和 launcher 应用。

1.4 非框架托管配置（10.1.68.25 及以上版本）

本节介绍非框架托管应用初始化 mPaaS 框架的简易方法。

只需在应用的 window 及 navigationController 创建完成后，调用以下方法即可，不再需要创建 bootloader、隐藏框架 window 等操作。
支持不继承 DFNavigationController。
若 App 有多个导航栏，且需要在不同导航栏中打开不同离线包，在切换导航栏后需重新设置容器的导航栏。

2. 发布小程序

启动小程序之前，您需要先通过 mPaaS 控制台发布该小程序。

2.1 进入小程序后台

2.2 配置虚拟域名

如果您是第一次使用，请先在 小程序 > 小程序发布 > 配置管理 中配置虚拟域名。虚拟域名可以为任意域名，建议使用您的企业域名，如 test.com。

2.3 创建小程序

进入 mPaaS 控制台，完成以下步骤：

点击左侧导航栏的 小程序 > 小程序发布。
在打开的小程序包列表页，点击新建。
在 新建小程序 窗口，填写小程序的 ID 和小程序名称，点击确定。其中，小程序 ID 为任意 16 位数字，例如 2018080616290001。
在小程序 App 列表下，找到新增的小程序，点击添加。
在基本信息栏，完成以下配置：
- 版本：填写小程序包的版本号，例如 1.0.0.0。
- 客户端范围：选择小程序 App 对应的 iOS 客户端最低版本和最高版本。在这个范围内的客户端 App 可以启动对应的小程序，否则无法启动。这里最低版本可以填写 0.0.0，最高版本可以不填，代表客户端所有版本都可以启动这个小程序。
  说明：这里的版本号指当前客户端 App 的版本号，请参考工程 Info.plist 中的 Product Version 字段。
- 图标：点击 选择文件 上传小程序包的图标。第一次创建小程序时必需上传图标。示例图标如下：
- 文件：上传小程序包资源文件，文件格式为 .zip。我们为您准备了一个 mPaaS 示例小程序（点此下载），您可以直接上传。
在配置信息栏，完成以下配置：
- 主入口 URL：必填，小程序包的首页，例如 /index.html#page/tabBar/component/index。
- 其他配置保持默认即可
勾选 已确认以上信息准确，提交后不再修改。
点击提交。

2.4 发布小程序

进入 mPaaS 控制台，完成以下步骤：

点击左侧导航栏的 小程序 > 小程序发布 > 小程序正式包管理。
在打开的小程序包列表页中，选择您要发布的小程序包与版本，点击 创建发布。
在创建发布任务栏，完成以下配置：
- 发布类型：选择正式发布类型。
- 发布描述：选填。
点击确定完成发布创建。

3. 启动小程序

完成上述步骤之后，进入对应的页面时，调用框架提供的 startTinyAppWithId 接口方法加载小程序。

[MPNebulaAdapterInterface startTinyAppWithId:appId params:nil];

若打开小程序时需要传递参数，可以通过 param 参数进行设置。其中 param 包含 page 和 query 两个字段：

page：用来指定打开特定页面的路径。
query：用来传入自定义的参数。多个键值对以 & 进行拼接。

NSDictionary *param = @{@"page":@"pages/card/index", @"query":@"own=1&sign=1&code=2452473"};
[MPNebulaAdapterInterface startTinyAppWithId:appId params:dic];