Note: Custom modules and this article are intended only for experienced Android developers. Creating a custom module requires advanced knowledge and skills in developing native mobile apps.

Custom Modules are a Pega Mobile Client feature that allow custom native code to run in the context of a Pega application running inside Pega Mobile Client. Custom modules can be used to integrate native libraries, add features, and address requirements for devices or Android features that are specific to a user's use cases.

This article covers the essentials of developing a PMC Custom Module:

• Creating a module
• Basic concepts
• Running the module from DevKit when targeting the Pega Mobile Client application
• Calling the APIs provided by a custom module from the JavaScript context
• Deploying the module to an instance

Prerequisites

Custom Module DevKit is part of Pega Mobile Client and can be obtained through Digital Delivery. The version of  DevKit that you download and use must match the version of Pega Mobile Client that is being used in the Mobile Channel. Use of Custom Module DevKit has the following additional requirements: 

• A computer running the Android Studio development environment and developer command-line tools. 
• Java Development Kit (JDK) version 11.
• Optional: Chrome DevTools, configured to work with a device or simulator.

Note: This article assumes that the developer already has basic Kotlin/Android knowledge. Bear in mind that developing a custom module requires the ability to develop native code, and work with Android Studio IDE as well as the command-line tools that are part of Custom Module DevKit. 

Creating a module 

To create a new module, download and unzip the Module DevKit package, navigate to its root in the terminal, and then enter the following command:

./gradlew createModule --moduleDirectory=<path_to_new_module_directory> --moduleName=<module_name>

For example:

./gradlew createModule --moduleDirectory=/Users/dev/modules --moduleName=SampleModule

Result The createModule command initializes an empty module project with the necessary configuration. 

Note: Creating modules in the Module DevKit package root directory is not recommended, as it will make migrating to newer DevKit versions more difficult.

After you run the command, open the DevKit project by using Android Studio.

Basic concepts

The sample project that you generate when you create the module is an Android Library Project, with DevKit's gradle-pega-android-module plugin applied to its build.gradle.kts file. The plugin automatically adds all PMC dependencies. The sample project has 2 plugins that are relevant to Pega integration: an application plugin, and a WebView plugin subclass.

Application Plugin

The application plugin implements the DefaultLifecycleObserver interface, allowing custom modules to react to Android application life cycle callbacks . Each application plugin type has to be annotated with @ApplicationPlugin in order to be properly instantiated by Pega Mobile Client.

For more information on application plugins, see the documents on writing application plugins, located in the docs folder in the Module DevKit package root directory.

WebViewPlugin subclass 

The WebViewPlugin subclass provides an extension point to the web view and allows custom JavaScript APIs to be exposed. These APIs can then be used by applications created using Pega Platform. Each web view manages a set of instances of all registered plugins. Apart from extending the WebViewPlugin, PMC web view plugins are also annotated by @JavaScriptPlugin, which defines the methods and properties exposed to JavaScript. 

The following code is an example of the PMSWebViewPlugin subclass that is generated when you create a new module:

@Suppress("UNUSED")
@JavaScriptPlugin(PLUGIN_NAME)
class SampleModuleWebViewPlugin(webView: PMCWebView) : WebViewPlugin(webView) {

    @JavaScriptAPI
    fun sayHello(name: JavaScriptValue, promise: JavaScriptPromise) {
        ...
    }

    companion object {
        internal const val PLUGIN_NAME = "samplePlugin"
    }
}

For information on further aspects of developing WebView Plugins, see the document located in the docs folder in the Module DevKit docs directory.

Knowing the basic custom module elements, it is now possible to have a look at the WebView plugin method that is being exposed by a plugin. The WebView plugin method has a simple implementation of the sayHello(name, promise) method that returns a greeting for a given name. For example: 

class SampleModuleWebViewPlugin(webView: PMCWebView) : WebViewPlugin(webView) {
...

    @JavaScriptAPI
    fun sayHello(name: JavaScriptValue, promise: JavaScriptPromise) {
        promise.resolve(JavaScriptValue("Hello ${name.stringValue}!"))
    }
}

By default, the methods and properties are exposed in a window.pms.plugins object under a camel-cased version of the plugin class name, but can be changed by passing an argument to the @JavaScriptPlugin annotation. In this example, "samplePlugin" is passed, so the APIs will be available as window.pms.plugins.samplePlugin.

Running the module from DevKit

1. Navigate to an existing Mobile Channel page, or create a new Mobile Channel page. 
2. On the right side of the screen, click the Pega Mobile Preview icon, and then click Copy link. 
3. In the Devkit root directory, in the mobileChannelUrl  key, paste the link into gradle.properties. 
4. Sync the project.
5. Click the run button to deploy the application to a device or emulator.

The PMC should then boot, fetch the channel configuration, and launch the app. DevKit won't apply any branding to LaunchScreen, and uses the default launch screen instead. 

Calling the APIs provided by a custom module from the JavaScript context

At this point, it is not yet possible to invoke the custom module JavaScript API from the Pega Platform UI, but it can be invoked from the Chrome DevTools JavaScript console. To do so, enter chrome://inspect/ in the Chrome search bar, and then press Inspect under one of the web views of the running app (either on the emulator or on the device). In the DevTools window, navigate to the Console tab and enter the following command:

window.pms.plugins.samplePlugin.sayHello("Developer").then(function(result) {
    console.log(result) 
}) 

When the code runs, the results are printed to the Android Studio Logcat console. The results returned by the native code can then be easily examined while developing the native module code. 

Deploying the module

Pega Platform 8.4 and later

Starting from Pega Platform 8.4, the Custom Module DevKit includes a task that provides for seamless packaging and uploading of custom modules. To package and upload a custom module, navigate to the root of the Custom Module DevKit package and enter the following command:

./gradlew uploadModule --moduleName=<module_name> -PmobileChannelUrl=<channel_url> -Pusername=<username> -Ppassword=<password>

The channel URL in the above command is the same URL that was placed in gradle.properties when running the module code for the first time. If the channel URL is still there, you do not need to pass it again in this command.

Once you have entered and run the above command, the module will be available to be added in the Custom modules section of the Configuration tab in the Mobile Channel. After adding the module, it will be included in the next build of your mobile app.

Pega Platform 8.3

For earlier versions of Pega Platform you must use the package task, which will build the framework package. Navigate to the root of the Custom Module DevKit package, and then enter and run the following command:

./gradlew packageModule --moduleName=<module_name>

For example:

./gradlew packageModule --moduleName=SampleModule

A zip file is created and saved with the same name as the custom module inside the build directory in the root Custom Module DevKit folder. You can then download the branding assets template file from https://community.pega.com/knowledgebase/articles/branding-assets-templates-pega-mobile-client. Unzip the module package from the build directory into a new directory called modules-android, in the root of the downloaded template package. Upload the zipped assets files to the Mobile Channel, and then build the app. Your module will be be included in the next build of your mobile app.

To learn more about integrating your Custom Module with Pega Platfrom UI please refer to https://collaborate.pega.com/discussion/invoking-pega-mobile-client-custom-modules-pega-platform-ui