Skip to content

Commit

Permalink
fix(ios): remove unused initialization param of HippyRootView
Browse files Browse the repository at this point in the history 
and update integration documents
  • Loading branch information
@wwwcg
wwwcg committed Jan 26, 2024
1 parent 3ce4476 commit ecb95d2
Show file tree
Hide file tree
Showing 6 changed files with 271 additions and 135 deletions.
186 changes: 119 additions & 67 deletions docs/en-us/ios/integration.md
View file
Original file line number Diff line number Diff line change
@@ -1,89 +1,141 @@
# iOS Integration
# iOS integration

> Note: the following documents assume that you have some experience in iOS development.
> Note: The following documents assume that you already have some experience in iOS development.
This tutorial shows how to integrate Hippy into an iOS project.
This tutorial describes how to integrate Hippy into an existing iOS project.

---

# Integrate with Cocoapods
## 1. Use Cocoapods to integrate iOS SDK

1. install [cocoapods](https://cocoapods.org/), Hippy iOS SDK [version query](https://cocoapods.org/pods/hippy)
[CocoaPods](https://cocoapods.org/) is a popular package management tool for iOS and macOS development. We'll use this to add Hippy's iOS Framework to an existing iOS project.

2. Create a podfile file under user-defined project directory with the following text
It is recommended to use Homebrew to install CocoaPods. The installation command is as follows:

```text
# keep podfile directory structure
install! "cocoapods", :preserve_pod_file_structure => true
platform :ios, '11.0'
# replace TargetName with user's project name
target TargetName do
# use latest version of Hippy
pod 'hippy'
# if you want to assign Hippy version, say, 2.0.0
#pod 'hippy', '2.0.0'
end
```
```shell
brew install cocoapods
```

> Tip: When integrating versions `2.13.0` to `2.16.x`, if you access hippy in the form of a static link library, you need to set the `force_load` compilation parameter to load all symbols of hippy.
>
> `2.17.x` and above versions do not need to be configured.
>
> There are many ways to set `force_load`, you can choose any of the following configurations, and adjust according to the actual situation:
>
> * Directly set `*-force_load "${PODS_CONFIGURATION_BUILD_DIR}/hippy/libhippy.a"*` in the configuration of `Other Linker Flags` in the Build Settings of the target corresponding to the main project.
>
> * Add `post_install hook` in the Podfile configuration file of the App project, and add `force_load` to xcconfig by yourself.
>
The specific steps are as follows:

3. Execute in the command line
1. First, determine the Hippy iOS SDK version to be integrated, such as 2.17.0, and record it, which will be used in the Podfile.

```text
pod install
```
> You can go to "[version query address](https://github.com/Tencent/Hippy/releases)" to check the latest version information
4. open the project by the `.xcworkspace` file generated by cocoapods.
2. Secondly, prepare the Podfile file of the existing iOS project

# Write Code to Start Debugging or Load Business Code
The Podfile file is the configuration file of the CocoaPods package management tool. If the current project does not have this file, the simplest way to create it is to use the CocoaPods init command and execute the following command in the iOS project file directory:

Hippy provides a code-splitting loading interface and a non-code-splitting loading interface. All service packages are carried through `HippyRootView`. Creating a business is to create a `RootView`.
```shell
pod init
```

## Using the code-splitting load interface
The generated Podfile will contain some demo settings that you can adjust according to the purpose of the integration.

``` objectivec
/** This method is suitable for the following scenarios.
* Prepare the JS environment and load package 1 before the business is started, and load package 2 when the business is started to reduce package loading time
* We suggest package 1 as the base package, which is not related to the business and contains only some common base components, common to all businesses
* Package 2 is loaded as business code
*/
In order to integrate Hippy SDK into the project, we need to modify the Podfile file, add hippy to it, and specify the integrated version. The modified Podfile should look like this:

// Load package 1 address first to create execution environment
//commonBundlePath being package 1's path
NSURL * commonBundlePath = getCommonBundlePath();
HippyBridge *bridge = [[HippyBridge alloc] initWithBundleURL: commonBundlePath
moduleProvider: nil
launchOptions: nil];
// Create rootview by bridge and package2 address
- (instancetype)initWithBridge:(HippyBridge *)bridge
businessURL:(NSURL *)businessURL // business package address
moduleName:(NSString *)moduleName // business package startup function name
initialProperties:(NSDictionary *)initialProperties // initialize parameters
shareOptions:(NSDictionary *)shareOptions // configuration parameters (advanced)
isDebugMode:(BOOL)isDebugMode // whether debug mode
delegate:(id<HippyRootViewDelegate>)delegate // rootview load callback
```text
platform:ios, '11.0'
```
# TargetName is most likely your project name
targetTargetName do
# Specify here the hippy version number recorded in step 1
pod 'hippy', '2.17.0'
end
```

> IMPORTANT NOTE:
>
> When integrating some historical versions from `2.13.0` to `2.16.x`, if hippy is accessed in the form of a static link library, the `force_load` compilation parameter needs to be set to load all symbols of hippy, otherwise the Hippy application will not be able to run. The versions that need to be set are as follows:
>
> `2.13.0` to `2.13.13`
>
> `2.14.0` to `2.14.10`
>
> `2.15.0` to `2.15.7`
>
> `2.16.0` to `2.16.5`
>
> `force_load` can be set in a variety of ways. You can choose any of the following configurations and adjust according to the actual situation:
>
> * Add `*-force_load "${PODS_CONFIGURATION_BUILD_DIR}/hippy/libhippy.a"*` directly to the Build Settings - `Other Linker Flags` configuration of the corresponding target of the main project.
>
> * Add `post_install hook` to the Podfile configuration file of the App project, and add `force_load` to xcconfig by yourself.
>

3. Finally, execute in the command line

```shell
pod install
```

After the command is successfully executed, use the project file with the `.xcworkspace` suffix generated by CocoaPods to open the project.

## 2. Write SDK access code and load local or remote Hippy resource package

## Using the non-code-splitting load interface
The initialization of Hippy SDK only requires two steps:

``` objectivec
Subpackage loading interface - (instancetype)initWithBundleURL:(NSURL *)bundleURL // package address
moduleName:(NSString *)moduleName // business package startup function name
initialProperties:(NSDictionary *)initialProperties // initialize parameters
shareOptions:(NSDictionary *)shareOptions // configuration parameters (advanced)
isDebugMode:(BOOL)isDebugMode // whether debug mode
delegate:(id <HippyRootViewDelegate>)delegate // rootview load callback
1. Initialize a HippyBridge instance. HippyBridge is the most important concept of Hippy. It is a bridge for communication between the Native side and the JS side. It also carries the main context information of the Hippy application.

2. Initialize a HippyRootView instance through the HippyBridge instance. HippyRootView is another important concept of Hippy applications. Hippy applications will be displayed by it. Therefore, it can be said that creating a business means creating a `HippyRootView`.

Currently, Hippy provides subcontracted loading interfaces and non-subcontracted loading interfaces. The usage methods are as follows:

### Method 1. Use subcontracting loading interface

```objective
/** This method is suitable for the following scenarios:
* Prepare the JS environment before the business starts, and load package 1. When the business starts, load package 2 to reduce package loading time.
* We recommend package 1 as a basic package, which has nothing to do with the business. It only contains some common basic components and is common to all businesses.
* Package 2 is loaded as business code
*/
// First load package 1 and create a HippyBridge instance
// Assume commonBundlePath is the path of package 1
// Tips: For detailed parameter description, please refer to the header file: HippyBridge.h
NSURL *commonBundlePath = getCommonBundlePath();
HippyBridge *bridge = [[HippyBridge alloc] initWithDelegate:self
bundleURL:commonBundlePath
moduleProvider:nil
launchOptions:your_launchOptions
executorKey:nil];
// Then create a HippyRootView instance through the above bridge and package 2 address
// Assume businessBundlePath is the path of package 2
// Tips: For detailed parameter description, please refer to the header file: HippyRootView.h
HippyRootView *rootView = [[HippyRootView alloc] initWithBridge:bridge
businessURL:businessBundlePath
moduleName:@"Your_Hippy_App_Name"
initialProperties:@{}
shareOptions:nil
delegate:nil];
// Finally, set the frame for the generated rootView and mount it on the specified VC.
rootView.frame = self.view.bounds;
rootView.autoresizingMask = UIViewAutoresizingFlexibleHeight | UIViewAutoresizingFlexibleWidth;
[self.view addSubview:rootView];
// At this point, you have completed the initialization of a Hippy application. The SDK will automatically load resources and start running the Hippy application.
```

### Method 2. Use non-packaging loading interface

```objective
//Similar to the above-mentioned use of the subcontracted loading interface, you first need to create a HippyBridge instance.
// The difference is that when creating a HippyRootView instance, there is no need to pass in the business package, that is, businessBundlePath. You can create it directly using the following interface.
// Tips: For detailed parameter description, please refer to the header file: HippyRootView.h
- (instancetype)initWithBridge:(HippyBridge *)bridge
moduleName:(NSString *)moduleName
initialProperties:(nullable NSDictionary *)initialProperties
shareOptions:(nullable NSDictionary *)shareOptions
delegate:(nullable id<HippyRootViewDelegate>)delegate;
```

!> Regardless of whether rootview is initialized with or without code-splitting, if **isdebugmode** is YES, all parameters will be ignored and the test dataset is loaded directly using the npm local service. Using code-splitting loading can be combined with a series of strategies, such as pre-loading bridge, global single bridge, and so on, to optimize page opening speed.
> A simple sample project is provided in the Hippy repository, including all the above access codes, as well as more notes.
>
> It is recommended to refer to this example to complete the integration of the SDK into existing projects: [iOS Demo](https://github.com/Tencent/Hippy/tree/master/examples/ios-demo)
>

!> Using subpackage loading, you can combine a series of strategies, such as preloading bridge in advance, global single bridge, etc. to optimize page opening speed.
Loading

0 comments on commit ecb95d2

Please sign in to comment.