Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 4 Next »

This page describes a way to inject a custom Native Plugin (NPI) into the Android and iOS Mobile Application Framework (MAF) Platforms. The NPI is a standalone/self contained part of an application and gives you a way to incorporate your own functionality into your Apps through the MAF Platforms.

Android Native Plug-in Information

Native Plugin Requirement

For the NPI, the following information is needed:

  • Android Library Project packaged into an Android Archive File (AAR).
  • A JSON Configuration file that provides the following (The JSON string will be passed to the Fragment):
    • Fragment Classname (Full Class Name including the package name) of the initial custom Fragment included in the Library Project.
    • Any arguments/parameters that the NPI needs.

 

Example JSON File:

{
  “FragmentClassName”: “com.mobilesmith.rallyconnector.ui.LoginFragment”,
  “rally_url”: “https://rally1.rallydev.com”,
  “company_name”: “MobileSmith”
}

System Frameworks

The Android MAF Platform builds towards the following versions of the Android Platform:

  • Compile SDK Version: 22
  • Build Tools Version 22.0.1
  • Target API Version: 22
  • Minimum SDK Version: 14
  • The builds include the following libraries:
  • Android Support Compat Library v7:22.0.0 - ‘com.android.support:appcompat-v7:22.0.0’
  • Google Play Services Locaion v7.0.0 - ‘com.google.android.gms:play-services-location:7.0.0’
  • Google Play Services Maps v7.0.0 - ‘com.google.android.gms:play-services-maps:7.0.0’
  • Google Play Services Analytics v7.0.0 - ‘com.google.android.gms:play-services-analytics:7.0.0’
  • DiskLRUCache Library v2.0.2 - ‘com.jakewharton:disklrucache:2.0.2’
  • HttpMine v4.2 - ‘org.apache.httpcomponents:httpmime:4.2’
  • Flurry Analytics v3.4.0
  • Google Cloud Messaging Library
  • Picasso Library v 2.5.2 - ‘com.squareup.picasso:picasso:2.5.2’
  • Spring Android v1.0.1
    • ‘org.springframework.android:spring-android-core:1.0.1.RELEASE’
    • ‘org.springframework.android:spring-android-rest-template:1.0.1.RELEASE’
  • Scribe (OAuth Library) v1.3.7 - ‘org.scribe:scribe:1.3.7’
  • GreenRobot EventBus v2.4.0 - ‘de.greenrobot:eventbus:2.4.0’

The NPI must provide any 3rd party libraries in the deployed AAR file.

The MAF builds are currently built towards JDK 1.5.

 

Supported Tools

We support the following tools for NPI development:

  • Android Studio 1.2 Integrated Development Environment
  • Genymotion Android emulators
  • Espresso 2.0 for Automate UI Testing
  • Spoon (1.1.1) for Automated UI Device Testing

Design and Implementation Constraints

Android MAF Platform will provide a Fragment container for 3rd party NPI User Interface elements. These Fragment containers will allow the Platform the ability to embed the NPI’s inside the current UI without changing the underlying code.

Code Guidelines:

  • Anything going against the Play Store guidelines is prohibited in third party code.
  • Exceptions are not handled outside of the custom Fragment: if the custom Fragment does not handle the exception the app will crash.

 

Android Fragments

Android Fragments (from the Android Support Library v4) should be used as a UI Container for NPI’s, it represents a portion of the UI in an Android Activity. This will allow the Android MAF Framework to control most of the screen that has the NPI. The Fragment approach will allow the Custom Native Plugin to have its own lifecycle, receive its own input events, and the ability to swap out its own Fragments without the knowledge of the MAF Platform.

The Android MAF Platform will pass in an Android Bundle to the Fragment that includes the
following:

  • JSON Configuration String (Bundle key = “json_config”) - this will contain the JSON provided in the JSON Configuration File.
  • UI Fragment Container Id (Bundle key = “container_view_id”) - this should be used to replace the current fragment in the Platform:
final FragmentTransaction fragmentTransaction = activity.getSupportFragmentManager().beginTransaction();
fragmentTransaction.replace(container_view_id, fragment);
if (addToBackStack) {
    fragmentTransaction.addToBackStack(null);
}
fragmentTransaction.commit();

Android Plugin Deployment Information

The Custom Native Plugin should be package in an AAR file with the structure of an Android library as described in the Android Build System Documentation

http://tools.android.com/tech-docs/new-build-system/aar-format

EventBus Library

The Android MAF platform utilizes a publish/subscribe event bus for communications between the platform components. This event bus can be utilized by the NPI for NPI to NPI communication and in the future NPI to MAF/MAF to NPI communication. For more information about the EventBus, see:

https://github.com/greenrobot/EventBus

 

Android Caveats

The following are caveats with Native Plugins on Android:

MapFragments

Map Fragments, used to display Google Maps, are currently not supported in the NPI framework. A workaround is display the map in a WebView.

ActionBar Title

Changing the ActionBar Title is currently not supported in the NPI framework. This functionality will be provided at a later date.

Nested Views

Nested views can cause some latency issues with the NPI’s inside the MobileSmith platform, since the NPI resides several layers deep. See the following App View Hierarchy:

 

iOS Native Plugin Information

The iOS MobileSmith platform primarily works by transitioning to various UIViewController subclasses. One might represent a list of data configured in the MobileSmith website, another might have an e-mail feedback form, etc. This gives applications built in the MobileSmith platform a lot of built-in functionality they could utilize, but sometimes an application has needs for some very specific functionality.

NPIs allow app designers to include a custom UIViewController instance in their application that can be selected and navigated to similar to the other internal UIViewController subclasses. Currently the “scope” of an NPI is limited to what can be accomplished by a UIViewController implementation. An NPI cannot modify the Info.plist file of the app, change the application icon, or modify the Xcode linker flags, for example.

There are two primary components that make up an NPI: a ZIP file that contains all third-party code and resources needed by the device, and a configuration JSON file that is setup in the MobileSmith website with configuration information that could be utilized by the NPI code.

 

iOS NPI Zip File

The zip file has only one required component: a library (.a) file containing the code for the custom UIViewController (or UINavigationController) subclass. In addition it could contain any number of resource bundles or additional library files that are required. If there are multiple items that need to be included in the zip, be sure to select the items in the Finder, right-click and select “Compress # items…” instead of compressing their common parent directory.

NPI Configuration

In the app design UI, the designer can enter in arbitrary key/value pairs to associate with the NPI. This will be converted into a JSON file with a single object and key/value pairs for each field, and the JSON will be provided to the NPI at runtime.

There is only one required key in the configuration JSON for iOS: “ViewControllerClassName.” This is represented by the “iOS Class Name” field in the MobileSmith UI. The value should be a string representing the name of the UIViewController (or UINavigationController) subclass representing the main entry point into the NPI. This JSON is also provided to the UIViewController subclass when it is initialized, so it is possible to have any number of other keys there for the NPI to look for (for example, a server URL). There is only going to be one NPI Configuration JSON that will be used by both Android and IOS NPIs (if both apps are built in the MobileSmith platform).

 

 

 

  • No labels