Integration into a Host App

Refer to the general Getting Start page to know how to setup the project and integrate the dependency of PH into an App.

Setup

1. Ensure the App you are integrating PH into is aligned with the version of Gradle PH uses.

   Current Gradle version: 7.4.2

2. Ensure the following dependency versions are aligned with PH:

   // Required
   buildToolsVersion = "30.0.3"
   gradleBuildToolsVersion = "7.4.2"
   daggerVersion = "2.46.1"
   navigationComposeVersion = "2.5.2"
   
   // Optional
   mockkVersion = "1.11.0"
   assertJVersion = "3.22.0"
   coroutinesVersion = "1.5.0"
   timberVersion = "5.0.1"
   kotlinxSerializationVersion = "1.4.1"

   You can find the latest dependency versions at [TBC].

   As a best practice, you should handle the versioning using mobile-ci.json instead of hardcoding versions as ext properties in your root build.gradle.

3. Add PlatformHub dependency to your app build.gradle

dependencies {
    // Platform-hub
    implementation "com.skyrin.mobilebanking:platformhub:<LATEST-VERSION>"
}

Integrate PlatformHub

1. Create a class in the app module called AppPlugin. Alternatively, you can create an app-plugin module in in the project and add the AppPlugin class to it.

2. Implement the AppPlugin which implements the plugin interface of platformhub and implement the necessary override methods (helps decoupling between the current App and PlatformHub)

   @Singleton
   class AppPlugin @Inject constructor(): Plugin {
   
       override fun init(
         context: Context,
         configurationFiles: Map<String, InputStream>
       ) {}
   
       override val policy = Policy {}
   
       override fun subscribeOnStartup(
          subscription: SharedFlow<EventStreamOutput>,
          eventStream: BaseMessage.EventStream
        ) {}
   
       override fun onReceive(message: BaseMessage.Query): JSONObject = JSONObject("{}")
   
       override fun onReceive(message: BaseMessage.Command) {}
   
   }

3. Create a class that implements PlatformHubInitializer interface in the main app module which is responsible for configuring the plugins the app will be using.

   @Singleton
   class PlatformHubInitializerImpl @Inject constructor(
      @ApplicationContext private val context: Context
   ) : PlatformHubInitializer {

       @Inject
       internal lateinit var platformHub: PlatformHub

       @Inject
       internal lateinit var appPlugin: AppPlugin

       @Inject
       internal lateinit var otherPlugin: OtherPlugin

       override val plugins: List<Pair<Plugin, Map<String, InputStream>>>
          get() = listOf(
              Pair(
                  otherPlugin,
                  mapOf(
                      "config-1" to context.assets.open("example-config.json")
                  )
              ),
              Pair(appPlugin, emptyMap())
          )

       // if you want to use topics, override the following:
       override val topics: TopicsConfiguration
          get() = objectFromJson(context.assets.open("app-topics-config.json"))

        // Call this function in your application class
        fun setup() {
            platformHub.init(context, this)
        }
   }

:::note

To send a message from the app to any other plugin (i.e. send initial message), you will have to use the AppPlugin. The AppPlugin is a standard requirement to communicate with other plugins. The Host App can only perform queries, commands and events via the AppPlugin.

  // Use the `messageSender` from the `AppPlugin` to send your initial message
  // The initial message can be any of the available message types
  appPlugin.messageSender.requestNavigation(
      navigationRequest = ActivityNavigationRequest(
      messageName = "ShowHelloWorldScreen",
      pluginName = "HelloWorldPlugin"
    ),
    plugin = appPlugin
  ).let { it as? ActivityNavigationResponse }
  ?.also { startActivity(it.intent(requireContext(), null)) }

:::

4. In the application class of your app, initialise the PlatformHubInitializerImpl class and call the setup() method to setup and initialise PlatformHub.

   @HiltAndroidApp
   class PlatformHubEnabledApplication : Application() {
   
      @Inject
      internal lateinit var platformHubInitializer: PlatformHubInitializerImpl
   
      override fun onCreate() {
          super.onCreate()
   
          platformHubInitializer.setup()
      }
   }

5. Build and run the App

---

Adding new Topic

In order to introduce new topic, define its name and topic messages in global app topics configuration:

{
  "topics": [
    {
      "topicName": "NewTopicName",
      "topicMessages": ["NewTopicMessageOne", "NewTopicMessageTwo"]
    }
  ]
}

In addition, at least one publisher and subscriber shall be defined in plugins policy.

Define schemas for topic messages

TopicNames with TopicMessages are declared globally in app-topics-config.json therefore theirs schemas should be declared on global app level.

publishing side:

PublishToTopic.TopicStream.NewTopicName.NewTopicMessageOne.OutputPayload.schema.json

subscribing side:

SubscribeToTopic.TopicStream.NewTopicName.NewTopicMessageOne.InputPayload.schema.json

More details here

Additional steps

You should provide backwards compatibility to the current App, so that it can be launched without PlatformHub.

1. Configure the gradle variants

   buildTypes {
       standaloneDebug {
         buildConfigField "boolean", "PLATFORMHUB_ENABLED", "false"
       }
       standaloneRelease {
         buildConfigField "boolean", "PLATFORMHUB_ENABLED", "false"
       }
       platformHubDebug {
         buildConfigField "boolean", "PLATFORMHUB_ENABLED", "true"
       }
       platformHubRelease {
         buildConfigField "boolean", "PLATFORMHUB_ENABLED", "true"
       }
   }

2. By using the appropriate PlatformHub variant you can either enable or disable the PlatformHub initialisation.

   @HiltAndroidApp
   class PlatformHubEnabledApplication : Application() {
   
       // [...]
   
       override fun onCreate() {
          super.onCreate()
   
          if (BuildConfig.PLATFORMHUB_ENABLED) {
              // Initialise PlatformHub and other plugins
              // [...]
          }
      }
   }

3. PlatformHub offers optional extensions allowing smooth navigation between Activities, Fragments and Composables. Details can be found here.

---

Interacting with PlatformHub

You can find more information about plugins at Consuming plugins.