全部产品
云市场

iOS 小程序基础接入

更新时间:2020-05-09 09:43:28

要接入 iOS 小程序,您需要完成以下几大步骤:

  1. 添加 SDK:使用 Xcode 插件添加小程序组件。
  2. 配置工程:要运行小程序的功能,需进行工程配置。
  3. 发布小程序包:构建前端 .zip 包,并在控制台发布小程序包。
  4. 加载小程序包:进入对应的页面时,加载小程序。
  5. 预置小程序包:除了在线加载小程序包外,您还可以选择将小程序包预置到客户端中。

关于此任务

结合 代码示例,参照操作步骤,完成小程序接入 iOS 客户端。代码示例中包括小程序的依赖 SDK 和接入的代码示例。

添加 SDK

添加 SDK 分为 插件接入方式cocoapods 接入方式

插件接入方式

使用 Xcode 插件添加小程序组件。

xcode plugin

小程序自身会提供众多的 JSAPI 和 OpenAPI 能力,因此在插件中选择小程序组件后,相应的依赖组件也会默认添加到工程中。

cocoapods 接入方式

  1. 搭建 mPaaS cocoapods 环境,参见 基于原生框架且使用 CocoaPods 接入
  2. 按照下方示例修改 podfile,引入小程序。
    1. # mPaaS Pods Begin
    2. plugin "cocoapods-mPaaS"
    3. source "https://code.aliyun.com/mpaas-public/podspecs.git"
    4. mPaaS_baseline '10.1.60'
    5. platform :ios, '9.0'
    6. target 'MPTinyAppDemo_pod' do
    7. // 小程序
    8. mPaaS_pod "mPaaS_TinyApp"
    9. end
    说明:工程中每次操作接入和升级时都要确保下面的资源存在。
    资源配置

配置工程

在配置工程时,您需要:

如果您的 App 生命周期并没有交给 mPaaS 框架托管,您还需进行 非框架托管配置

初始化容器

启动容器

  • 为了使用 Nebula 容器,您需要在程序启动完成后调用 SDK 接口,对容器进行初始化。必须在 DTFrameworkInterface- (void)application:(UIApplication *)application beforeDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions 中进行初始化。

    1. - (void)application:(UIApplication *)application beforeDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    2. {
    3. // 初始化容器
    4. [MPNebulaAdapterInterface initNebula];
    5. }
  • 若您需要使用 预置离线包自定义 JSAPIPlugin 等功能,请将上方代码中的 initNebula 替换为下方代码中的 initNebulaWith 接口,传入对应参数对容器进行初始化。

    • presetApplistPath:自定义的预置离线包的包信息路径。
    • appPackagePath:自定义的预置离线包的包路径。
    • pluginsJsapisPath:自定义 JSAPI 和 Plugin 文件的存储路径。
      1. - (void)application:(UIApplication *)application beforeDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions
      2. {
      3. // 初始化容器
      4. NSString *presetApplistPath = [[NSBundle mainBundle] pathForResource:[NSString stringWithFormat:@"MPCustomPresetApps.bundle/h5_json.json"] ofType:nil];
      5. NSString *appPackagePath = [[NSBundle mainBundle] pathForResource:[NSString stringWithFormat:@"MPCustomPresetApps.bundle"] ofType:nil];
      6. NSString *pluginsJsapisPath = [[NSBundle mainBundle] pathForResource:[NSString stringWithFormat:@"Poseidon-UserDefine-Extra-Config.plist"] ofType:nil];
      7. [MPNebulaAdapterInterface initNebulaWithCustomPresetApplistPath:presetApplistPath customPresetAppPackagePath:appPackagePath customPluginsJsapisPath:pluginsJsapisPath];
      8. }
      说明initNebulainitNebulaWithCustomPresetApplistPath 是两个并列的方法,不要同时调用。

定制容器

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

    1. - (void)application:(UIApplication *)application afterDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    2. {
    3. // 定制容器
    4. [MPNebulaAdapterInterface shareInstance].nebulaVeiwControllerClass = [MPH5WebViewController class];
    5. [MPNebulaAdapterInterface shareInstance].nebulaNeedVerify = NO;
    6. [MPNebulaAdapterInterface shareInstance].nebulaUserAgent = @"mPaaS/Portal";
    7. [MPNebulaAdapterInterface shareInstance].nebulaCommonResourceAppList = @[@"77777777"];
    8. }
  • 属性含义如下:

名称 含义 备注
nebulaVeiwControllerClass H5 页面的基类 默认为 h5webviewcontroller,若需指定所有 H5 页面的基类,可直接设置此接口。
nebulaWebViewClass WebView 的基类 默认为 UIWebView,若需指定 WebView 的基类,可直接设置此接口。
nebulaUserAgent 当前应用的 UserAgent -
nebulaNeedVerify 是否验签,默认为 YES 配置离线包 时未上传私钥文件,此值需设为 NO,否则离线包加载失败。
nebulaPublicKeyPath 离线包验签的公钥 配置离线包 时上传的私钥对应的公钥。
nebulaCommonResourceAppList 公共资源包的 appId 列表 -
errorHtmlPath 当 H5 页面加载失败时展示的 HTML 错误页路径 默认读取 MPNebulaAdapter.bundle/error.html

更新离线包

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

  1. - (void)application:(UIApplication *)application afterDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions
  2. {
  3. // 定制容器
  4. [MPNebulaAdapterInterface shareInstance].nebulaVeiwControllerClass = [MPH5WebViewController class];
  5. [MPNebulaAdapterInterface shareInstance].nebulaNeedVerify = NO;
  6. [MPNebulaAdapterInterface shareInstance].nebulaUserAgent = @"mPaaS/Portal";
  7. [MPNebulaAdapterInterface shareInstance].nebulaCommonResourceAppList = @[@"77777777"];
  8. // 全量更新离线包
  9. [[MPNebulaAdapterInterface shareInstance] requestAllNebulaApps:^(NSDictionary *data, NSError *error) {
  10. NSLog(@"");
  11. }];
  12. }

初始化完成后,效果如下:

after initialization

配置小程序

配置权限

info.plist 中配置以下 App 权限:

  • NSBluetoothAlwaysUsageDescription:蓝牙权限(iOS 13 中新增)。
  • NSCameraUsageDescription:相机权限。
  • NSPhotoLibraryUsageDescription:相册权限。
  • NSLocationWhenInUseUsageDescription:定位权限。

permission

配置动态库

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

FalconLooks

非框架托管配置

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

non-host

启动 mPaaS 框架

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

launch mpaas

说明:启动框架必须在当前应用 windownavigation 初始化完成后调用,否则无法生效。

创建应用启动器

创建继承 DTBootLoader 的子类,重写 createWindowcreateNavigationController 方法,返回当前应用自己的 windownavigationControlle

  • 设置 window:当前应用的 keyWindow。
  • 设置 navigationController:当前应用 keyWindow 的 rootviewcontroller,必须继承 DFNavigationController

DTBootLoader

DFNavigationController

指定应用启动器

DTFrameworkInterfacecategory 中重写方法,指定当前应用自己的 bootloader,并隐藏 mPaaS 框架默认的 windowlauncher 应用。

bootloader

发布小程序包

小程序包的格式与离线包一样,同样也是 .amr 格式。完成以下步骤生成小程序包:

  1. 构建前端 .zip 包:使用小程序 IDE 插件构建前端 zip 包,如下图所示:
    export
  2. 发布小程序包:
    1. 登录 mPaaS 发布平台,上传生成的 .zip 包。具体操作步骤,参见 创建小程序包
    2. 小程序包管理 页面,发布您上传的小程序包。具体操作步骤,参见 发布小程序包

加载小程序包

进入对应的页面时,调用框架提供的 startTinyAppWithId 接口方法加载小程序。

  1. [MPNebulaAdapterInterface startTinyAppWithId:appId params:nil];

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

  • page: 用来指定打开特定页面的路径。
  • query: 用来传入自定义的参数。多个键值对以 & 进行拼接。
  1. NSDictionary *param = @{@"page":@"pages/card/index", @"query":@"own=1&sign=1&code=2452473"};
  2. [MPNebulaAdapterInterface startTinyAppWithId:appId params:dic];

预置小程序包

针对业务上重要且不愿受网络限制的小程序包,您可直接将小程序包预置在客户端中进行加载,而不用去创建发布任务。主要有以下几步:

  1. 进入 mPaaS 控制台,在 实时发布 > 小程序包管理 中下载您需要预置的小程序 .amr 包和配置文件。
    download
  2. 将从控制台下载的小程序包和配置文件,添加到工程中,具体路径为您在初始化容器时指定的预置离线包路径。
    add
  3. 进入对应的页面时,调用框架提供的 startTinyAppWithId 接口方法加载小程序。
    1. [MPNebulaAdapterInterface startTinyAppWithId:appId params:dic];

配置灰度白名单

要使用小程序包管理中的白名单灰度发布功能,需要确保服务端已获取客户端的唯一标识,客户端需要在 MPaaSInterface 的 category 中配置用户唯一标识,根据应用实际情况,在 userId 方法中返回 App 的唯一标识,例如用户名、手机号、邮箱等。

  1. #import <mPaas/MPaaSInterface.h>
  2. @implementation MPaaSInterface (Portal)
  3. - (NSString *)userId
  4. {
  5. return @"mPaaS";
  6. }
  7. @end