Android project requirements
System requirements:- minSdk = 26
- compileSdk = 34
- Android Gradle Plugin 8.1.1
- Kotlin 1.9.10
Installing the library
- Add the maven repository in your projectβs
settings.gradle.kts
file:
- Add the library as a dependency in your
app/build.gradle.kts
file:
Library dependencies
Impactful dependencies:- Koin 3.2.2, including the implementation for Koin Context Isolation
- Compose BOM 2023.09.01 + Compose Compiler 1.5.3
- Accompanist 0.32.0
- Kotlin Coroutines 1.7.3
- OkHttp BOM 4.11.0
- Retrofit 2.9.0
- Coil Image Library 2.3.0
- Gson 2.10.1
Public API
The SDK library is managed through theFlowxSdkApi
singleton instance, which exposes the following methods:
Name | Description | Definition |
---|---|---|
init | Initializes the FlowX SDK. Must be called in your applicationβs onCreate() | fun init(context: Context, config: SdkConfig, customComponentsProvider: CustomComponentsProvider? = null) |
checkRendererCompatibility | Checks the renderer version compatibility with the deployed services | suspend fun checkRendererCompatibility(action: ((Boolean) -> Unit)?) |
startProcess | Starts a FlowX process instance, by returning a @Composable function where the process is rendered. | fun startProcess(processName: String, accessToken: String, params: JSONObject = JSONObject(), isModal: Boolean = false, closeModalFunc: ((processName: String) -> Unit)? = null): @Composable () -> Unit |
continueProcess | Continues an existing FlowX process instance, by returning a @Composable function where the process is rendered. | fun continueProcess(processUuid: String, accessToken: String, isModal: Boolean = false, closeModalFunc: ((processName: String) -> Unit)? = null): @Composable () -> Unit |
executeAction | Runs an action from a custom component | fun executeAction(action: CustomComponentAction, params: JSONObject? = null) |
getMediaResourceUrl | Extracts a media item URL needed to populate the UI of a custom component | fun getMediaResourceUrl(key: String): String? |
replaceSubstitutionTag | Extracts a substitution tag value needed to populate the UI of a custom component | fun replaceSubstitutionTag(key: String): String |
updateAccessToken | Updates the access token inside the renderer | fun updateAccessToken(token: String) |
Configuring the library
To configure it, call this method in your projectβs application classonCreate()
method:
Name | Description | Type | Requirement |
---|---|---|---|
context | Android application Context | Context | Mandatory |
config | SDK configuration parameters | ai.flowx.android.sdk.process.model.SdkConfig | Mandatory |
customComponentsProvider | Provider for the @Composable /View custom components | ai.flowx.android.sdk.component.custom.customComponentsProvider? | Optional. Defaults to null . |
custom components
implementation is explained in its own section.
Sample
SdkConfig
data for the config
parameter above are:
Name | Description | Type | Requirement |
---|---|---|---|
baseUrl | URL to connect to the FlowX back-end environment | String | Mandatory |
imageBaseUrl | URL to connect to the FlowX Media Library module of the CMS | String | Mandatory |
language | The language used for retrieving enumerations and substitution tags | String | Optional. Defaults to en . |
validators | Custom validators for form elements | Map<String, (String) -> Boolean>? | Optional. |
themeTokensJsonFileAssetsPath | Android assets relative path to the theme tokens json file | String? | Optional. When null internal theme will be used. |
themeComponentsJsonFileAssetsPath | Android assets relative path to the theme components json file | String? | Optional. When null internal theme will be used. |
Custom validators
Thecustom validators
map is a collection of lambda functions, referenced by name (i.e. the value of the key
in this map), each returning a Boolean
based on the String
which needs to be validated.
For a custom validator to be evaluated for a form field, its name must be specified in the form field process definition.
By looking at the example from above - mapOf("exact_25_in_length" to { it.length == 25 })
- if a form element should be validated using this lambda function, in the process definition it must specifiy a custom validator named "exact_25_in_length"
.
Theming
To override the rendererβs internal theme, thethemeTokensJsonFileAssetsPath
and themeComponentsJsonFileAssetsPath
parameters should contain some values, representing Android assets relative paths to the corresponding JSON file for tokens and components.For example, their values could look like in the example from above:
file://android_asset/...
, where ...
is the relative path within your projectβs assets/
directory.
Using the library
Check renderer compatibility
To check the renderers compatibility with the FlowX deployed services, use thesuspend
function checkRendererCompatibility
:
Sample
Start a FlowX process
To start a new instance of a FlowX process, use thestartProcess
function:
Parameters
Parameter | Description | Type | Requirement |
---|---|---|---|
processName | The name of the process | String | Mandatory |
accessToken | The access token which allows access to the FlowX backend services | String | Mandatory |
params | The starting params for the process, if any | JSONObject | Optional. If omitted, if defaults to JSONObject() |
isModal | Flag indicating whether the process can be closed at anytime by tapping the top-right close button | Boolean | Optional. It defaults to false . |
closeModalFunc | Lambda function where you should handle closing the process when isModal flag is true | ((processName: String) -> Unit)? | Optional. It defaults to null . |
This wrapper activity must display only the
@Composable
returned from the SDK (i.e. it occupies the whole activity screen space).
Sample
Resume a FlowX process
To resume an existing instance of a FlowX process, use thecontinueProcess
function:
Parameters
Parameter | Description | Type | Requirement |
---|---|---|---|
processUuid | The UUID string of the process | String | Mandatory |
accessToken | The access token which allows access to the FlowX backend services | String | Mandatory |
isModal | Flag indicating whether the process can be closed at anytime by tapping the top-right close button | Boolean | Optional. It defaults to false . |
closeModalFunc | Lambda function where you should handle closing the process when isModal flag is true | ((processName: String) -> Unit)? | Optional. It defaults to null . |
This wrapper activity must display only the
@Composable
returned from the SDK (i.e. it occupies the whole activity screen space).
Sample
Handling authorization token changes
When the access token changes, in can be updated in the renderer using theupdateAccessToken
method:
Custom components
The container application should decide which custom component view to provide using thecomponentIdentifier
configured in the UI designer.A custom component receives data to populate the view and actions to execute, as described below. To handle custom components, an implementation of the
CustomComponentsProvider
interface should be passed as a parameter when initializing the SDK:
- by implementing the CustomComposableComponent interface
- by implementing the CustomViewComponent interface
Sample
CustomComposableComponent
To provide the custom component as a @Composable function, you have to implement theCustomComposableComponent
interface:
CustomComposable
object is an interface defined like this:
Sample
CustomViewComponent
To provide the custom component as a classical Android View function, you have to implement theCustomViewComponent
interface:
CustomView
object is an interface defined like this:
Sample
Execute action
The custom components which the container app provides will contain FlowX actions to be executed.In order to run an action you need to call the
executeAction
method:
Parameters
Name | Description | Type | Requirement |
---|---|---|---|
action | Action object extracted from the data received in the custom component | ai.flowx.android.sdk.component.custom.CustomComponentAction | Mandatory |
params | Parameters needed to execute the action | JSONObject? | Optional. It defaults to null |
Get a substitution tag value by key
key
.
It returns:
- the keyβs counterpart, if the
key
is valid and found - the empty string, if the
key
is valid, but not found - the unaltered string, if the key has the wrong format (i.e. not starting with
@@
)
Get a media item url by key
key
.
It returns the URL
string of the media resource, or null
, if not found.
Known issues
- shadows are rendering only on Android >= 28 having hardware acceleration enabled