PlatformHub Integration

This concise guide provides developers and technical teams with essential steps to successfully integrate PlatformHub into any application. It covers evaluating framework compatibility, planning and preparation, integration steps, best practices, testing and deployment. Follow this guide to streamline the integration process and ensure seamless transition to enhance your application with PlatformHub.

Planning and preparation

Understand the application where PlatformHub needs to be integrated to determine the approach for the integration.

• Can PlatformHub be integrated as core capability or it needs to be a flavour?
• Are there multiple markets supported by the app?
• If yes, then do we want to enable PlatformHub selectively for some markets?

Specifically look into application startup. When PlatformHub initialises, it initialises all the plugins in the system as well. So it should be the first step in the initialising process.

Platform Specific Integration Steps

aOS

iOS

Testing and deployment

• Identifying test strategy: An approach needs to be determined to confirm that PlatformHub is initialised properly and able to communicate with desired plugins successfully. To do so,
  • Existing plugins can be adopted, or
  • If App Dynamics is integrated, a plugin/adapter can be created for App Dynamics. Messages(breadcrumbs) can be sent to App Dynamics via the AppPlugin confirming PlatformHub started successfully.
• Performance benchmarking: Adopting PlatformHub will change the way different components are integrated in the application. To access the impact of PlatformHub adoption, it is recommended to have performance benchmarking in place before adoption.

Best Practices

1. Aligned dependencies versions with PlatformHub to avoid unexpected behaviour.
2. Avoid version hardcoding. It is recommended to use mobile-ci to declare dependencies' versions.
3. Ensure you have one application class. If you don't want to do any changes in the existing application existing class, then create a new application class that inherits/extends from it (aOS specific).
4. It is required to use declarative and reactive UI (i.e Jetpack compose/SwiftUI).

How to integrate your plugin or adapter plugin with their dependencies

Implementing a new plugin

If you are implementing a new plugin from scratch, read the following points to understand how you should deal with each dependancy type that your plugin may have.

Dependency with another plugin

• This is the ideal dependancy and the solution we are striving for.
• Easy integration since both plugins are in the same PH ecosystem, allowing them to communicate with each other directly using the different messages provided by PlatformHub.

What do you need to do?

• Nothing! Everything is ready for your new plugin to start communicating with the other plugin.

sequenceDiagram
participant Plugin A
participant Plugin B
    Plugin A->>Plugin B: message
    Plugin B->>Plugin A: response

Dependency with a legacy library

• Your new plugin needs to communicate with an existing legacy library.
• Your plugin has a direct dependancy on a legacy library, having to communicate directly with it. There is no mediator in between like, for example, the host app.

What do you need to do?

• The legacy library needs to be adapted by creating an Adapter Plugin around it. This will enable its communication with other plugins.
• You will need to communicate with the maintainers of the legacy library and agree who should implement the Adapter Plugin. It might be your team that will have to create the adapter.
• Ideally, the Adapter Plugin should adapt all the library's existing legacy public interface.
• If the previous point is unrealistic to achieve given time and budget constraints, you should adapt those legacy public interfaces that your plugin needs to use, contributing to the process of adapting the existing legacy interface in an incremental way. With this approach, little by little different teams will be contributing to adapt different parts of the legacy interface until we get to the point where it gets fully adapted.

sequenceDiagram
participant Plugin A
box rgb(232, 255, 236) Legacy Library
participant Adapter Plugin
participant Legacy code
end
Note left of Legacy code: The Adapter Plugin is <br/>implemented inside <br/>the Legacy Library
    Plugin A->>Adapter Plugin: message
    Adapter Plugin->> Legacy code: legacy message
    Legacy code->>Adapter Plugin: legacy response
    Adapter Plugin->>Plugin A:response

Dependency with another legacy library via the host app (GMX)

• Your plugin needs to communicate with a legacy library but instead of talking to it directly, like in the previous point, it will do it through the host app.

What do you need to do?

• The first priority is to adapt the legacy library itself so your plugin can talk to it directly, allowing us to delete the code in the host app that was previously mediating between both libraries (in GMX this scenario is quite common when a legacy journey needs to launch another legacy journey). To implement this solution follow the steps described in the previous subsection: Dependency with a legacy library.
• If the previous point is not feasible then adapt the host app code with a small Adapter Plugin. This approach is not ideal since it does not reduce our tech debt. Eventually this adapter plugin in the host app will have to be removed when the dependancy legacy plugin is rewritten or adapted.

sequenceDiagram
participant Plugin A
box rgb(232, 255, 236) Host App
participant Adapter Plugin
end
Note right of Adapter Plugin: The Adapter Plugin is <br/>implemented inside <br/>the host app
participant Legacy Library
    Plugin A->>Adapter Plugin: message
    Adapter Plugin->> Legacy Library: legacy message
    Legacy Library->>Adapter Plugin: legacy response
    Adapter Plugin->>Plugin A:response

Dependency with host app (GMX) functionality

• Your plugin needs to communicate with some legacy code in the host app.

What do you need to do?

• You will need to write an adapter plugin within the host app to enable its communication with your plugin.
• Before you start the implementation of a new adapter plugin in the host app, understand if there is already a plugin in the host app that shares the same responsibility and if it makes sense contributing to it instead of creating a new one. The idea is to take the chance we are creating all these new host app plugins to refactor and group together related logic under the same plugin. This way, at some point in the future, we will be able to potentially extract these plugins into their own libraries in Nexus, reducing the code complexity in the host app.

sequenceDiagram
participant Plugin A
box rgb(232, 255, 236) Host App
participant Adapter Plugin
participant Legacy code
end
Note right of Adapter Plugin: The Adapter Plugin is <br/>implemented inside <br/>the host app
    Plugin A->>Adapter Plugin: message
    Adapter Plugin->>Legacy code: legacy message
    Legacy code->>Adapter Plugin: legacy response
    Adapter Plugin->>Plugin A:response

Adapting a legacy library into an Adapter Plugin

You are writing an Adapter Plugin in a legacy library.

Although creating adapters around the legacy libraries does generate technical debt (as they will be demised once they are rewritten from scratch as a new plugin in PlatformHub) they are required to enable the legacy library to communicate with other plugins in the app. There are 2 advantages when creating an adapter plugin:

1. It enables the direct, uncoupled communication with other plugins without needing the host app to mediate in between, allowing us to remove any existing code in the host app that was previously mediating between legacy libraries. This effectively will reduce the size and complexity of our host app.
2. The adapter plugin's interface should be very similar, if not the same, to the new plugin's interface that will eventually substitute it, paving the way for its future integration with the host app and other plugins.

When creating an Adapter Plugin consider the following:

• If you have the time, budget and the legacy library's public interface is small enough, you should consider adapting all its public interface.
• Otherwise we will be following an incremental approach where you will be adapting only those specific public interfaces that you actually need. Over time, different teams will contribute incrementally to the adapter until all the legacy public interface is fully adapted to PlatformHub.

Let's see, in the points below, how we should deal with the different types of dependencies your legacy library may have.

Dependency with a plugin

• Your legacy library needs to communicate with a plugin.
• This is the ideal dependancy and the solution we are striving for.
• Once we have adapted the legacy library, the integration with the dependancy plugin is straight forward since they both will be in the same PH ecosystem, allowing them to communicate with each other directly using the different messages provided by PlatformHub.

What do you need to do?

• Write and Adapter Plugin for our legacy library, or if there is already one, add to it the necessary logic to communicate with the dependancy plugin via PlatformHub.

sequenceDiagram
box rgb(232, 255, 236) Legacy Library
participant Legacy code
participant Adapter Plugin
end
Note right of Legacy code: The Adapter Plugin is <br/>implemented inside <br/>the Legacy Library
participant Plugin A
    Legacy code->>Adapter Plugin: legacy message
    Adapter Plugin->>Plugin A: message
    Plugin A->>Adapter Plugin:response
    Adapter Plugin->>Legacy code: legacy response

Legacy library with internal dependencies

Your legacy library probably has internal dependencies with other libraries that it imports via mobile-ci.json. These dependancy libraries are necessary for your legacy library to work correctly, hence they are allowed and there is no need to remove them.

You don't need to do anything.

Dependency with another legacy library via host app (GMX)

Your legacy library may have a dependancy with another legacy library with which it communicates via the host app. There is no need to refactor this logic.

You don't need to do anything.

Dependency with host app (GMX) legacy code

Your legacy library may have to communicate with the host app. There is no need to refactor this logic.

You don't need to do anything.