Mobile Platform as a Service:Getting started

This topic describes how to integrate the H5 container and offline package components into an existing iOS client project using CocoaPods.

Use SDK

This topic uses the official H5 container and offline package demo to describe how to use the H5 container SDK in baselines 10.1.60 and later.

The process of using the H5 container SDK involves the following five steps:

1. Initialize configurations

2. Invoke the container

3. Enable bidirectional communication between H5 and Native

4. Load offline packages

5. H5 container instrumentation

1. Initialize configurations

1.1. Initialize the container

• To use the Nebula container, you must call the SDK to initialize the container after the application starts. This initialization must occur in the - (void)application:(UIApplication *)application beforeDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions method of DTFrameworkInterface. Override this method in the DTFrameworkInterface + (ProjectName) category provided by the mPaaS framework.

    - (void)application:(UIApplication *)application beforeDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
        // Initialize the container
        [MPNebulaAdapterInterface initNebula];
    }

• To use features such as preset offline packages, custom JSAPIs, and Plugins, replace the initNebula interface with the initNebulaWith interface and pass the required parameters to initialize the container.

  • presetApplistPath: The path of the package information file for custom preset offline packages.

  • appPackagePath: The path of the custom preset offline packages.

  • pluginsJsapisPath: The storage path for custom JSAPI and Plugin files.

    - (void)application:(UIApplication *)application beforeDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
        // Initialize the container
        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];
    }

    Note

    The initNebula and initNebulaWithCustomPresetApplistPath methods are mutually exclusive and cannot be called at the same time.

• mPaaS lets you configure the request interval for miniapp packages globally or for individual packages.

  • Global configuration: You can set the update frequency for offline packages or miniapps using the following code when you initialize the container.

    [MPNebulaAdapterInterface shareInstance].nebulaUpdateReqRate = 7200;

    In the code, `7200` is the default global update interval in seconds. You can change this value to set a custom global request interval for offline packages. The valid range is 0 to 86400 seconds (24 hours). A value of 0 indicates no limit on the request interval.

  • Individual configuration: This configures the interval for a single miniapp package. In the console, go to Individual Configuration > Add Offline Package > Extended Information and enter {"asyncReqRate":"1800"} to set the request interval. For more information, see the Extended Information section in Create an H5 offline package.

1.2 Customizing containers

• If needed, you can customize the container by setting the properties of MPNebulaAdapterInterface. You must set these properties in the - (void)application:(UIApplication *)application afterDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions method of DTFrameworkInterface. Otherwise, the container's default configurations will overwrite your custom settings.

    - (void)application:(UIApplication *)application afterDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    {
        // Customize the container
        [MPNebulaAdapterInterface shareInstance].nebulaVeiwControllerClass = [MPH5WebViewController class];
        [MPNebulaAdapterInterface shareInstance].nebulaNeedVerify = NO;
        [MPNebulaAdapterInterface shareInstance].nebulaUserAgent = @"mPaaS/Portal";
        [MPNebulaAdapterInterface shareInstance].nebulaCommonResourceAppList = @[@"77777777"];
    }

• The properties are described as follows:

  Property	Meaning	Remarks
  nebulaViewControllerClass	The base class for HTML5 pages.	Defaults to `H5WebViewController`. To specify a custom base class for all HTML5 pages, set this property. Important The base class must inherit from H5WebViewController.
  nebulaWebViewClass	Sets the base class for the WebView.	> 10.1.60: Defaults to H5WKWebView. A custom WebView must inherit from H5WKWebView. = 10.1.60: Customization is not supported.
  nebulaUseWKArbitrary	Sets whether to use WKWebView to load offline package pages.	> 10.1.60: Defaults to YES. = 10.1.60: Defaults to NO.
  nebulaUserAgent	Sets the User-Agent for the application.	The specified User-Agent is appended to the container's default UA.
  nebulaNeedVerify	Specifies whether to perform signature verification. The default value is YES.	If you did not upload a private key file when you configured the offline package, set this value to NO. Otherwise, the offline package will fail to load.
  nebulaPublicKeyPath	The path of the public key for offline package signature verification.	The path of the public key that corresponds to the private key uploaded when you configured the offline package.
  nebulaCommonResourceAppList	The list of appIds for public resource packages.	-
  errorHtmlPath	The path of the HTML error page to display when an HTML5 page fails to load.	By default, the container reads from MPNebulaAdapter.bundle/error.html.
  configDelegate	Sets the delegate for custom switches.	Allows you to globally modify the container's default switch values.

1.3 Non-framework-managed configuration

If your app's lifecycle is not managed by the mPaaS framework (a non-framework-managed project), you must perform additional configurations as described in this section. In this scenario, the app lifecycle is assigned to a custom delegate. If the mPaaS framework manages your app's lifecycle, no additional configuration is required.

• After the application's `window` and `navigationController` are created, call the following method. You no longer need to create a bootloader or hide the framework window.

• Inheriting from DFNavigationController is not required.

• If the app has multiple navigation bars and you need to open different offline packages in different navigation bars, you must reset the container's navigation bar after switching.

1.5. Configure non-framework-managed projects (for versions earlier than 10.1.68.25)

If your app's lifecycle is not managed by the mPaaS framework (a non-framework-managed project), you must perform the following additional configurations. If the mPaaS framework manages your app's lifecycle, no additional configuration is required.

1.4.1 Starting the mPaaS framework

In the didFinishLaunchingWithOptions method of the current application, call [[DTFrameworkInterface sharedInstance] manualInitMpaasFrameworkWithApplication:application launchOptions:launchOptions]; to start the mPaaS framework.

1.4.2 Create an Application Launcher

Create a child class that inherits from `DTBootLoader`. In this child class, rewrite the createWindow and createNavigationController methods to return the current application's `window` and `navigationController`.

• Set `window`: The `keyWindow` of the current application.

• Set `navigationController`: The `rootViewController` of the current application's `keyWindow`. It must inherit from `DFNavigationController`.

1.4.3 Specify the application launcher

In the `DTFrameworkInterface` category, rewrite the method to specify your application's custom bootloader and hide the default window and launcher application of the mPaaS framework.

2. Invoke the container

After the container is initialized, you can invoke an H5 container in one of three ways.

• Create an H5 container based on an online URL or a local HTML file. The following code provides an example:

  // Open an online URL
  [[MPNebulaAdapterInterface shareInstance] startH5ViewControllerWithParams:@{@"url": @"https://tech.antfin.com/products/MPAAS"}];
  // Open a local HTML page
  NSString *path = [[NSBundle mainBundle].bundlePath stringByAppendingFormat:@"/%@/%@", @"MPH5Demo.bundle", @"H52Native.html"];
  if ([path length] > 0) {
  [[MPNebulaAdapterInterface shareInstance] startH5ViewControllerWithParams:@{@"url": path}];
  }

• Create and automatically open an H5 container using a push that contains offline package information. The following code provides an example:

    [[MPNebulaAdapterInterface shareInstance] startH5ViewControllerWithNebulaApp:@{@"appId":@"90000000"}];

• Create an H5 container based on offline package information and return the H5 container instance. This method is typically used for a tab on the home page. The following code provides an example:

    [[MPNebulaAdapterInterface shareInstance] createH5ViewControllerWithNebulaApp:@{@"appId":@"90000000"}];

3. Enable bidirectional communication between H5 and Native

You can enable bidirectional communication between H5 and Native by calling JSAPIs and listening for specific events.

3.1. Call Native features from an HTML5 page

You can enable communication from H5 to Native by calling JSAPIs.

For more information about the JSAPIs supported by the Nebula container and their parameters, see Built-in JSAPIs.

Example

When a button on an HTML5 page is clicked, call the JSAPI method pushWindow to load a new page:

AlipayJSBridge.call('pushWindow', {
    url: 'https://tech.antfin.com',
    param: {
    readTitle: true,
    defaultTitle: true,
    // ...
    }
}, function(data) {alert('Call result'+JSON.stringify(data)); });

AlipayJSBridge description

AlipayJSBridge is a JSBridge automatically injected by the Nebula container. After the Window.onload event, the container generates a global variable named AlipayJSBridge and triggers the AlipayJSBridgeReady event. Because the injection is an asynchronous process, you must listen for the AlipayJSBridgeReady event before you call the interface.

The following code provides an example:

<h1>How to use the bridge</h1>

<script>
function ready(callback) {
  if (window.AlipayJSBridge) {
    callback && callback();
  } else {
    document.addEventListener('AlipayJSBridgeReady', callback, false);
  }
}

ready(function(){
  alert('bridge ready');
});
</script>

3.2. Call H5 features from a Native page

You can enable communication from Native to H5 by listening for specific events. For more information about the events supported by the Nebula container, see Event extension list.

document.addEventListener('back', function (e) {
    if(confirm('The back event was intercepted. Are you sure you want to go back?')) {
        // do something;
    }
}, false);

In addition to the events that the Nebula container supports by default, you can also define custom events on the Native side for the frontend to listen for.

// self: The VC where the current HTML5 page is located
// data: The parameters passed from Native to the frontend
// callBack: The callback after the frontend receives the event
[self callHandler:@"customEvent" data:@{@"key":@"value"} responseCallback:^(id responseData) {
        NSLog(@"Callback after the frontend receives the event: %@", responseData);
    }];

3.3. Extend Nebula container capabilities

If the basic bidirectional communication capabilities for HTML5 pages provided by the Nebula container do not meet your needs, you can extend Nebula:

• JSAPI: If you want to initiate a Native function call from an HTML5 page, such as displaying an ActionSheet or a contacts dialog box, you need to extend the JSAPI. A JSAPI lets you easily add Native function calls to an HTML5 page to implement specific features using a handler method. For more information about how to customize a JSAPI, see Customize JSAPIs.

• Plugin: To perform certain actions at specific times, such as when a user enters a page or when the container receives a request, you need to develop a plugin. Examples of actions include recording instrumentation data and modifying returned data. After you subscribe to the corresponding events in the plugin, you can process the data carried by the events in the handler. For more information about how to customize a plugin, see Customize plugins.

4. Load offline packages

Traditional online H5 technology is susceptible to network conditions, which can negatively affect the performance of HTML5 pages. To minimize the impact of the network on HTML5 page loading, you can encapsulate and package different services into an offline package. You can then deliver the package to the client through the publishing platform to update client resources. For more information, see Introduction to offline packages and Use offline packages.

5. H5 container instrumentation

When an HTML5 page loads, the Nebula container automatically monitors loading performance and captures related behavioral data and error data. For more information, see H5 container instrumentation.