Mobile Platform as a Service:Quick start

You can use the HTML5 container and offline package to implement the following functions: container initialization and invocation, bi-directional communication between HTML5 and Native, loading and use of offline packages, integration of the automatic tracking ability of the Nebula container, and check of tracking data.

Before you begin

The project already gets access to mPaaS. For more information, see the following content: Access based on an existing project and use of CocoaPods

Add the SDK

Use the cocoapods-mPaaS plug-in. This method is applicable to the access mode based on an existing project and use of CocoaPods.

1. In the Podfile file, use mPaaS_pod "mPaaS_Nebula" to add the dependencies of the HTML5 container component.

   

2. Run pod install to complete the access of HTML5 container.

Use the SDK

This topic describes how to use the HTML5 container SDK in baseline version 10.1.60 or later versions with the official demo of the HTML5 container and offline package.

Initialize the container

Start the container

• To use the Nebula container, you need to call the SDK API to initialize the container after the program is started. Initiate the container in - (void)application:(UIApplication *)application beforeDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions of DTFrameworkInterface. Override this method in the category DTFrameworkInterface + (project project name) provided by the mPaaS framework.

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

• If you need to use the preset offline package, customize JSAPI, and plug-in functions, replace the initNebula API in the previous code with the initNebulaWith API in the following code. Then pass in the corresponding parameters to initialize the container.

  • presetApplistPath: custom path of the preset offline package information.

  • appPackagePath: custom path of the preset offline package.

  • pluginsJsapisPath: storage path of custom JSAPI and custom plug-in 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: initNebula and initNebulaWithCustomPresetApplistPath are two methods for container initialization. Do not call both of them at the same time.

• Configure the time interval of requests for Mini program packages. mPaaS supports both global and individual configuration of the time interval.

  • Global configuration: You can use the following code to set the update request interval of offline packages or Mini programs during container initialization.

    [MPNebulaAdapterInterface shareInstance].nebulaUpdateReqRate = 7200;

    Where, 7200 indicates the global update request interval. 7200 is the default value. The unit is second. You can change this value to set the global interval of requests for offline packages. The value range is 0 to 86400 seconds (that is, 0 to 24 hours). 0 indicates that there is no limit on request interval.

  • Individual configuration: The time interval of requests is only set for the current Mini program package. You can go to Add Offline Package > Extended Information in the console and then enter {"asyncReqRate":"1800"} to set the time interval of requests. For details, see Extended information in Create HTML5 offline package.

Customize the container

• You can set the attributes in MPNebulaAdapterInterface to customize the container configuration when necessary. The configuration must be implemented in - (void)application:(UIApplication *)application afterDidFinishLaunchingWithOptions:(NSDictionary *)launchOptions of DTFrameworkInterface. Otherwise, the configuration will be overridden by the default configuration of the container.

   - (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 following table describes the attributes:

Update an offline package

Make a request for full information of offline packages after startup and check whether update packages are available on the server. To prevent impact on the startup speed, we recommend that you request calling after (void)application:(UIApplication \*)application afterDidFinishLaunchingWithOptions:(NSDictionary \*)launchOptions.

- (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"];

    // Full update of offline packages
    [[MPNebulaAdapterInterface shareInstance] requestAllNebulaApps:^(NSDictionary *data, NSError *error) {
        NSLog(@"");
    }];
}

The following figure shows the effect after the initialization is complete:

Configuration not managed by the framework

If the lifecycle of your app is managed by a custom delegate instead of the mPaaS framework, additional configuration is required, as shown in the following figure. If your app is managed by the mPaaS framework, skip this step.

Start the mPaaS framework

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

Note: To ensure successful startup of the framework, implement the call after the initialization of window and navigation of the current application is complete.

Create a bootloader

Create a subclass derived from DTBootLoader, rewrite the createWindow and createNavigationController methods, and return the window and navigationControlle of the current application.

• Set window: keyWindow of the current application.

• Set navigationController: rootviewcontroller of keyWindow of the current application, which must be derived from DFNavigationController.

Specify a bootloader

Rewrite the method in category of DTFrameworkInterface, specify the bootloader of the current application, and hide the default window and launcher applications of the mPaaS framework.

Invoke a container

After container initialization, you can evoke an HTML5 container. The following describes three invoking methods:

• Create an HTML5 container based on an online URL or local HTML file. Refer to the following code 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 an HTML5 container based on the received offline package information and use automatic push to open the container. Refer to the following code example:

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

• Create an HTML5 container based on the received offline package information and return the created HTML5 container instance. This is usually used on a tab of homepage. Refer to the following code example:

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

Implement bidirectional communication between HTML5 and native apps.

You can call JSAPIs and listen to certain events to implement bidirectional communication between HTML5 and native apps.

Call the native function on an HTML5 page

You can call JSAPIs to enable HTML5 to communicate with Native.

For details about JSAPI supported by the Nebula container and related parameters, see Built-in JSAPI.

Example

Call a JSAPI pushWindow to load a new page when a button is tapped on an HTML5 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 AlipayJSBridge is a JSBridge automatically injected by the Nebula container. After the implementation of Window.onload , the container will generate a global variable AlipayJSBridge and trigger an AlipayJSBridgeReady event.AlipayJSBridge injection is an asynchronous process. Therefore, listen to the AlipayJSBridgeReady event before calling an API.

Refer to the following code example:

<h1>bridge API usage instruction</h1>

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

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

Call HTML5 on a native page

You can listen to certain events to enable communication between the native and HTML5. For information about events supported by the Nebula container, see Extended event list.

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

In addition to default events supported by the Nebula container, you can use the following method on the Native end to define an event that the front end can listen.

// self: VC where the current HTML5 page is located
// data: parameter passed to the front end by native
// callBack: callback after the front end receives the event
[self callHandler:@"customEvent" data:@{@"key":@"value"} responseCallback:^(id responseData) {
        NSLog(@"callback after the front end receives the event: %@", responseData);
    }];

Expand Nebula container capabilities

If the basic bidirectional communication between HTML5 pages provided by the Nebula container is insufficient, you can expand the capabilities of Nebula.

• JSAPI: To call the native function on a page, for example, to display an ActionSheet or contacts dialog box, you need to expand a JSAPI. JSAPI allows you to use the handler method to add a native feature for an HTML5 page to implement a specific function. For detailed instructions, see Customize a JSAPI.

• Plugin: To finish certain events (such as recording tracking and modifying returned data) at a certain time point (such as when entering a page or receiving a request), you need to develop a plug-in. After subscribing to corresponding events, the plug-in can process data carried in the events in the handler. For detailed instructions, see Customize a plug-in.

Load an offline package

The traditional online HTML5 technology is subject to actual network environment, which may compromise the performance of HTML5 pages. To minimize network impact on HTML5 page loading, you can encapsulate different services as an offline package and deliver it to the client through the release platform to update client resources. For more information, see Introduction to offline packages and Use offline packages.

HTML5 container tracking

When an HTML5 page is loaded, the Nebula container will automatically monitor the loading performance and capture related behavior data and exception data. For more information, see HTML5 container tracking.