Hippy/docs/ios/integration.md

iOS 集成

注：以下文档都是假设您已经具备一定的 iOS 开发经验。

这篇教程，讲述了如何将 Hippy 集成到现有的 iOS 工程。

---

一、使用 Cocoapods 集成 iOS SDK

CocoaPods 是一个iOS和macOS开发中流行的包管理工具。我们将使用它把Hippy的iOS Framework添加到现有iOS项目中。

推荐使用Homebrew安装CocoaPods，安装命令如下：

brew install cocoapods

具体的操作步骤如下：

1. 首先，确定要集成的Hippy iOS SDK版本，如2.17.0，将其记录下来，接下来将在Podfile中用到。

   可到「版本查询地址」查询最新的版本信息

2. 其次，准备好现有iOS工程的 Podfile 文件

   Podfile 文件是CocoaPods包管理工具的配置文件，如果当前工程还没有该文件，最简单的创建方式是通过CocoaPods init命令，在iOS工程文件目录下执行如下命令：

   pod init
   

   生成的Podfile将包含一些demo设置，您可以根据集成的目的对其进行调整。

   为了将Hippy SDK集成到工程，我们需要修改Podfile文件，将hippy添加到其中，并指定集成的版本。修改后的Podfile应该看起来像这样:

   platform :ios, '11.0'
   
   # TargetName大概率是您的项目名称
   target TargetName do
   
       # 在此指定步骤1中记录的hippy版本号
       pod 'hippy', '2.17.0'
   
   end
   

   重要提示：

   集成2.13.0至2.16.x部分历史版本时，如以静态链接库形式接入hippy，需设置force_load编译参数来加载hippy所有符号, 否则将无法运行Hippy应用。需设置的版本如下：

   2.13.0 至 2.13.13

   2.14.0 至 2.14.10

   2.15.0 至 2.15.7

   2.16.0 至 2.16.5

   可通过多种方式实现设置force_load，可选如下任意一项进行配置，并结合实际情况自行调整：

   • 直接在主工程对应 target 的 Build Settings - Other Linker Flags 配置中添加 *-force_load "${PODS_CONFIGURATION_BUILD_DIR}/hippy/libhippy.a"*。

   • 在App工程的 Podfile 配置文件中添加 post_install hook，自行给 xcconfig 添加 force_load。

3. 最后，在命令行中执行

   pod install
   

   命令成功执行后，使用 CocoaPods 生成的 .xcworkspace 后缀名的工程文件来打开工程。

二、编写SDK接入代码，加载本地或远程的Hippy资源包

Hippy SDK的代码接入简单来说只需两步：

1、初始化一个HippyBridge实例，HippyBridge是Hippy最重要的概念，它是Native侧与JS侧进行通信的桥梁，同时也承载了Hippy应用的主要上下文信息。

2、通过HippyBridge实例初始化一个HippyRootView实例，HippyRootView是Hippy应用另一个重要概念，Hippy应用将由它显示出来，因此可以说创建业务也就是创建一个 HippyRootView。

目前，Hippy 提供了分包加载接口以及不分包加载接口,使用方式分别如下：

方式1. 使用分包加载接口

/** 此方法适用于以下场景：
 * 在业务还未启动时先准备好JS环境，并加载包1，当业务启动时加载包2，减少包加载时间
 * 我们建议包1作为基础包，与业务无关，只包含一些通用基础组件，所有业务通用
 * 包2作为业务代码加载
*/

// 先加载包1，创建出一个HippyBridge实例
// 假设commonBundlePath为包1的路径
// Tips：详细参数说明请查阅头文件: HippyBridge.h
NSURL *commonBundlePath = getCommonBundlePath();
HippyBridge *bridge = [[HippyBridge alloc] initWithDelegate:self
                                                  bundleURL:commonBundlePath
                                             moduleProvider:nil
                                              launchOptions:your_launchOptions
                                                executorKey:nil];

// 再通过上述bridge以及包2地址创建HippyRootView实例
// 假设businessBundlePath为包2的路径
// Tips：详细参数说明请查阅头文件: HippyRootView.h
HippyRootView *rootView = [[HippyRootView alloc] initWithBridge:bridge
                                                    businessURL:businessBundlePath
                                                     moduleName:@"Your_Hippy_App_Name"
                                              initialProperties:@{}
                                                   shareOptions:nil
                                                       delegate:nil];

// 最后，给生成的rootView设置好frame，并将其挂载到指定的VC上。
rootView.frame = self.view.bounds;
rootView.autoresizingMask = UIViewAutoresizingFlexibleHeight | UIViewAutoresizingFlexibleWidth;
[self.view addSubview:rootView];

// 至此，您已经完成一个Hippy应用的初始化，SDK内部将自动加载资源并开始运行Hippy应用。

方式2. 使用不分包加载接口

// 与上述使用分包加载接口类似，首先需要创建一个HippyBridge实例，
// 区别是在创建HippyRootView实例时，无需再传入业务包，即businessBundlePath，直接使用如下接口创建即可
// Tips：详细参数说明请查阅头文件: HippyRootView.h
- (instancetype)initWithBridge:(HippyBridge *)bridge
                    moduleName:(NSString *)moduleName
             initialProperties:(nullable NSDictionary *)initialProperties
                  shareOptions:(nullable NSDictionary *)shareOptions
                      delegate:(nullable id<HippyRootViewDelegate>)delegate;

在Hippy 仓库中提供了一个简易示例项目，包含上述全部接入代码，以及更多注意事项。

建议参考该示例完成SDK到已有项目的集成：iOS Demo

!> 使用分包加载可以结合一系列策略，比如提前预加载bridge, 全局单bridge等来优化页面打开速度。