Electrode Native Container

The Electrode Native container is a native library similar to common third-party libraries that Android and iOS developers are familiar with. The container is generated entirely by the Electrode Native platform and packaged as a versioned Android Archive (AAR) library for Android and as a framework for iOS.

Each mobile application has its own custom Electrode Native container.

What's inside a Container ?

The Electrode Native container includes the following:

  • The MiniApps
    The MiniApps are packaged inside a single JavaScript bundle containing all of the JavaScript code of all the MiniApps.

  • The MiniApps assets
    the MiniApps assets are the fonts and images that are used by the MiniApps.

  • The MiniApps native dependencies
    The MiniApps native dependencies are all of the native dependencies that MiniApps directly or indirectly depend on. React Native is one native dependency but it also includes third-party native modules (react-native-maps, react-native-vector-icons, react-native-electrode-bridge) or platform APIs.

  • Additional native dependencies
    Some native dependencies do not depend directly or indirectly on the MiniApps. These dependencies are primarily native platform API implementations as well as some third-party native modules that are only used from the mobile application side. These additional dependencies are uncommon.

  • Container-specific code
    An Electrode Native container includes some code that is exposed to mobile application developers to properly integrate a container in their mobile application. This consists mostly of code to initialize the container along with some utility code to access and deal with the MiniApps stored within.

Container publication

An Electrode Native container is completely generated by Electrode Native based on the MiniApps and specific native dependencies you want to include in it. The Container should be published in a central, team shared, location. Keeping it local to your machine has its benefits--for example to launch a MiniApp in the Electrode Native runner, or for development and experimentation use, but for the most part you'll want to publish your Electrode Native container.

Electrode Native offers two publishers for the Electrode Native container: Git and Maven:

  • The Maven publisher is used for an Android container. Upon generation of the Electrode Native container, and compilation of it, Maven publishes the resulting AAR artifact to a Maven repository of your choice--this can be your own custom Nexus for example.

  • The Git publisher can be used for both the Android or iOS container. When you generate a container, the Git publisher publishes the complete generated container project to a Git repository of your choice--probably GitHub.

A Container is versioned. Every time an Electrode Native container is re-generated, its version is updated. For the Maven publisher, the version is part of the AAR artifact. For the Git publisher, a Git tag is used to denote the version.

Because Electrode Native containers include some native code, they are primarily used during the development lifecycle of a mobile application version. You cannot use a newly generated Electrode Native container in a mobile application version that has already been released. When you update a Miniapp for an OTA update, a newly generated Electrode Native container is not included because you cannot ship native code through OTA.

Configuring container publication

The container publication configuration is part of the containerGenerator configuration object stored in a cauldron, so that it can be shared across users of the Cauldron. You should add your own configuration manually to the Electrode Native cauldron as currently there is not a command to support this.

The configuration object should be stored under a specific platform level in the Electrode Native cauldron file. A sample configuration is shown below.

"nativeApps":[
   {
      "name":"MyWeatherApp",
      "platforms":[
         {
            "name":"android",
            "config":{
               "containerGenerator":{
                  "containerVersion":"1.0.0",
                  "publishers":[
                     {
                        "name":"github",
                        "url":"[email protected]:user/myweatherapp-android-container.git"
                     },
                     {
                        "name":"maven",
                        "url":"http://user.nexus.repo.com:8081/nexus/content/repositories"
                     }
                  ]
               }
            }
         },
         {
            "name":"ios",
            "config":{
               "containerGenerator":{
                  "name":"github",
                  "targetRepoUrl":"[email protected]:user/myweatherapp-ios-container.git",
                  "containerVersion":"1.0.0",
                  "publishers":[
                     {
                        "name":"github",
                        "url":"[email protected]:user/myweatherapp-ios-container.git"
                     }
                  ]
               }
            }
         }
      ]
   }
]

The publishers array contains all the publishers you want to use to publish an Electrode Native container. In example shown above, we want to publish the Electrode Native container of MyWeatherApp Android to two destinations: a GitHub repository and a Maven repository. For the GitHub repository, the code of the Electrode Native container will be published and a Git tag will be used for the version. For the Maven repository, the Electrode Native container will be compiled and the resulting versioned AAR will be published to the Maven repository.

Maven publisher remarks

  • The Maven publisher can be used only for the Android platform.
  • You'll need to have a global gradle.properties file on your workstation (~/.gradle/gradle.properties) containing the Maven username and password to use for the publication: 
mavenUser=user
mavenPassword=password

Adding an Electrode Native container to your mobile application

This section describes how to add an Electrode Native container to your Android or iOS mobile application.

Android

A Container library can be added to a mobile Android application project in one of two ways:

  • By adding a dependency on the Electrode Native container AAR (recommended), or
  • By directly adding the Electrode Native container module to the Android project as a Git submodule

You will also need to update your build.gradle files with the following:

  • jcenter repository

We publish the react-native Maven artifact to jcenter. Therefore, you must make sure that jcenter is present in your list of repositories. The repositories are most commonly defined in your top-level project build.gradle.

repositories {
  jcenter()
  //...
}
  • resolution strategy

React Native includes some third-party libraries that might conflict with the versions you are using. For example, you might have issues with jsr305. If that is the case, add the following to your application module build.gradle

configurations.all {
  resolutionStrategy.force 'com.google.code.findbugs:jsr305:3.0.0'
  //...
}

In addition to the above resolution strategy for handling the jsr305 conflict, you might also run into a conflict with OkHttp. React Native depends on a specific version of the very popular networking library, OkHttp. If you are using this library in your application, you might be forced to align your version of OkHttp with the version included with the React Native version that you are using. This is due to the current React Native design.

  • okio linting

You might run into a conflict with the okio third party library which comes with React Native. It is a known issue. To resolve this issue, disable the lint check for InvalidPackage. You can also find solutions by searching for the okio conflict on the web.

lintOptions {
  disable 'InvalidPackage'
  //...
}
Adding the Container as an AAR

If a Maven publisher has been configured in the Electrode Native cauldron, Electrode Native will package and publish the Electrode Native container project as a Maven artifact containing the AAR file--either to a local or remote Maven repository.

By default, if a publisher is not configured in the Electrode Native cauldron, Electrode Native will publish the container to your local Maven repository located here: ~/.m2/repository.

The Maven artifact will include the following values:

  • Group ID : com.walmartlabs.ern
  • Artifact ID : {mobile-app-name}-ern-container
  • Version string : {container-version}

{mobile-app-name} is the name of the mobile application in the cauldron for the Electrode Native container that is being generated. For example, if the application name is walmart, the Electrode Native container artifact ID will be walmart-ern-container.

{container-version} is the version of the generated Electrode Native container. The container version can be in the form: x.y.z where x, y and z are integers. For example 1.2.3 is a valid container version. You can specify a version for a Container or, by default, the current version will be patched-bumped to the new version.

To add a dependency on the Electrode Native container, in your mobile application add the following code to the dependencies object of your application module build.gradle. Be sure to substitute the {mobile-app-name} and {container-version} to represent your application.

dependencies {
  compile('com.walmartlabs.ern:{mobile-app-name}-ern-container:{container-version}')
  //...
}

Note If you use or plan to use a locally generated Electrode Native container, make sure to declare mavenLocal repository in the list of repositories. This is located in the top-level project build.gradle.

repositories {
  mavenLocal()
  //...
}
Adding the container as a Git submodule

Alternatively, you can include an Electrode Native container in a mobile application by adding it as an Android module. Although this is not the recommended way to add third-party dependencies (the container being one) to an Android project, it is however possible and this might be the best process if you don't have a remote Maven repository that you can publish the container to.

To add the container library as an Android module, add a GitHub publisher to the cauldron. Then, when a new Container version is published, Electrode Native will publish the resulting project to a private or public GitHub repository. It will create a Git tag for each version of a container. You can then add the container Android module to your application project--managed as a Git submodule.

Note Do not edit the code of the container if you use this procedure even though adding the Container directly in your project makes its code editable. The container code should not be modified manually, as any custom modification will be lost the next time the container is generated.

Be sure to include the module in your project settings.gradle, and add a compile project directive to your application module build.gradle.

iOS

An Electrode Native container can be added as a dependency to an Xcode project in two ways:

  • Use a dependency manager such as Carthage (Cocoapods will be supported in the future) or,
  • Perform a manual installation
Using Carthage to add a container

To add a container using Carthage:

1) Create a Cartfile if you don't already have one, or open an existing Cartfile.
2) Add the following line to your Cartfile.

$ git "[email protected]:user/myweatherapp-ios-container.git" "v1.0.0"

3) Create a Cartfile.resolved file if you don't have one or open your existing Cartfile.resolved file.
4) Add the following line to your Cartfile.resolved file:

$ git "[email protected]:user/myweatherapp-ios-container.git" "v1.0.0"

5) Install your dependencies using the following command:

$ carthage bootstrap --no-build --platform ios
Manually adding a container

To manually add a container:

  1. Clone the container to <Your-WorkSpace>.

     $ [email protected]:user/myweatherapp-ios-container.git
  2. Open your project in Xcode and right click on Libraries.
  3. Select Add Files to <your project name>. Look for ElectrodeContainer.xcodeproj in the file directory where you cloned the repo above.

Additional Configuration

After installing the dependency, you will need to add additional configurations.

  1. In Xcode, choose <your project name> from the Project Navigator panel.
  2. Click <your project name> under TARGETS.
  3. From the General tab, locate Embedded Binaries and click +
  4. Select ElectrodeContainer.framework and click Add.
  5. In Build Phases, verify that ElectrodeContainer is in Target Dependencies, Link Binary With Libraries, and Embed Frameworks.

Initializing a Container

This section describes how to initialize a container for the Android and iOS platforms.

Android

Before accessing MiniApps that are stored within an Electrode Native container, the container needs to be initialized.

Initialization of a Container should ideally take place during startup of your mobile application. If you are using a class extending Application, you should place the container initialization call in the onCreate method of this class. If you are not using an Application class to initialize all libraries used by your mobile application, you should place the container initialization code wherever appropriate. It's best to have it initialized as soon as possible.

The initialization of a container is done as a single call of the initialize static method of the ElectrodeReactContainer class.

ElectrodeReactContainer.initialize(
    this /* Application instance */,
    new ElectrodeReactContainer.Config().isReactNativeDeveloperSupport(BuildConfig.DEBUG)
    /* Additional plugins configuration here */);

The first parameter to this method is the Application instance. In the sample call above, we use this as the call is made from an Application extending class.
The second parameter is the configuration of the container and React Native. In the sample above, we enable React Native developer support. In the sample we make use of BuildConfig.DEBUG to enable developer mode for debug builds only. You can adapt it for your application needs.

The initialize method might also contain additional parameters. Respectively, one parameter per plugin configuration. Not all plugins (APIs or third-party native modules) are configurable, so most of them (>90%) won't add an extra parameter to the initialize method. One configurable plugin is react-native-code-push for example, as you need to pass a deployment key to initialize this plugin, and it also has a debug mode that you can enable or disable.

iOS

Before accessing MiniApps stored within an Electrode Native container, you need to initialize the container. In iOS, we prefix our platform-specific files with Electrode.

Initialization of a Container should ideally take place during startup of your mobile application. Ideally it should take place in your AppDelegate.m in didFinishLaunchingWithOptions: method. Otherwise, you should call the container initialization wherever appropriate. It's best to have it initialized as soon as possible.

Initialization of Container is performed through the static method startWithConfigurations: of ElectrodeReactNative. 

    ElectrodeContainerConfig *containerConfig = [[ElectrodeContainerConfig alloc] init];
    containerConfig.debugEnabled = RnDevSupportEnabled;
    [ElectrodeReactNative startWithConfigurations:containerConfig];

The first parameter is an implementation of the ElectrodePluginConfig protocol we provide through ElectrodeContainer that allows you to configure for both ElectrodeContainer and React Native. In the sample above we use RnDevSupportEnabled, a static boolean constant, to decide if developer support should be enabled or not. You can adapt it for your application needs.

The startWithConfigurations: method might also take additional parameters such as the implementation of ElectrodePluginConfig for additional plugins, depending on your plugin dependencies. Specifically, one parameter per plugin configuration.
Note Not all plugins (APIs or third party native modules) are configurable, so most of them (>90%) won't add an extra parameter to the initialize method. One configurable plugin is react-native-code-push for example, as you need to pass a deployment key to initialize this plugin, and it also has a debug mode that you can enable or disable.

To learn more about configurable plugins, see url

Launching a MiniApp

Android

When a Container is generated, it will create one Activity for each MiniApp included in the container. For example, if you have a MiniApp named Hello, the container will create an Activity-extending class named HelloActivity. It will also be declared in the AndroidManifest.xml file of the container so that you can launch it from your mobile application without extra setup.

All of these activities are stored in the com.walmartlabs.ern.container.miniapps namespace.

To launch a MiniApp, all you have to do then, is start its corresponding Activity.
You can also pass initial properties to a MiniApp, which will be provided to the JavaScript MiniApp as properties in the componentWillMount React lifecycle. This might be useful if the MiniApp needs data when first launched.

  • Call the following static method of the ElectrodeMiniAppActivity class.
    The first parameter is the Intent instance that you will pass to startActivity, while the second parameter is a Bundle instance containing the data to provide to the MiniApp as key:value pairs.
public static void addInitialProps(@NonNull Intent intent, @NonNull Bundle bundle)

The generated Activities are very basic, and might not fulfill more advanced needs. If you need to use your own Activity subclass to host a MiniApp, you can directly extend the ElectrodeMiniAppActivity class and override the methods to your needs.

Note Be sure to override the following method and return the String corresponding to the MiniApp name hosted by this Activity--using the previous example, we would return "Hello".

protected String getMiniAppName()

If you cannot extend your own Activity from this one (you might already have a deep inheritance chain and Java does not support multiple inheritance) but roll your own, or host the MiniApp in a Fragment instead, then you'll need to use ElectrodeMiniAppActivity as a template to roll your own class.

iOS

When a Container is generated, it provides one UIViewController for each MiniApp included in the Container. For example, if you have a MiniApp named Hello, the container will create a UIViewController that contains the Hello miniapp--and it's the same UIViewController that you are already familiar with.

To launch a MiniApp, all you have to do then, is

  • Present its corresponding UIViewController by calling [[ElectrodeReactNative sharedInstance] miniAppWithName:@"<your-mini-app-name>" properties:nil]

  • You can also pass initial properties to a MiniApp, which will be provided to the JavaScript MiniApp as properties in the componentWillMount React lifecycle. This might be useful if the MiniApp needs data when first launched. To do this, pass an NSDictionary to the parameter property.

The generated UIViewController is basic and might not fulfill your advanced needs. If you would like to use your own subclass of the UIViewController, you must override viewDidLoad: in your UIViewController as shown below:

- (void)viewDidLoad {
    [super viewDidLoad];    
    UIViewController *viewController* =
    [[ElectrodeReactNative sharedInstance] miniAppWithName:@"<YourMiniAppName>" properties:nil];
    viewController.view.frame = [UIScreen mainScreen].bounds;
    [self.view addSubview:viewController.view];
}

- ern create-container
Create (generate) a Container locally without publishing it.
This command is rarely used in workflows as it does not allow remote publication of the generated container. This command is primarily used for specific development and experimentation purposes.

- ern cauldron (add/del/update> dependencies and - ern cauldron <add/del/update> miniapps
Given that a container contains MiniApps and native dependencies, every time you need to add, delete, or update MiniApps or native dependencies to your container, the container is regenerated and published (with a new version). This means every time you make use of an ern cauldron subcommand used to add, delete, or update MiniApps or native dependencies for a given non-released mobile application version, behind the scene a new container version is automatically re-generated and published.

- ern run-android`` and- ern run-ios`
These two commands generate a local container that includes your MiniApp along with its native dependencies and the container is used by the Electrode Native runner application project to launch your MiniApp.

results matching ""

    No results matching ""