Skip to main content

Android project requirements

System requirements:
  • minSdk = 26 (Android 8.0)
  • compileSdk = 35
The SDK library was build using:

Installing the library

  1. Add the maven repository in your project’s settings.gradle.kts file:
dependencyResolutionManagement {
    ...
    repositories {
        ...
        maven {
            url = uri("https://nexus-jx.dev.rd.flowx.ai/repository/flowx-maven-releases/")
            credentials {
                username = "your_username"
                password = "your_password"
            }
        }
    }
}
  1. Add the library as a dependency in your app/build.gradle.kts file:
dependencies {
    ...
    implementation("ai.flowx.android:sdk:9.0.0")
    ...
}

Library dependencies

Impactful dependencies:

Public API

The SDK library is managed through the Flowx singleton instance, which exposes the following methods:
NameDescriptionDefinition
initInitializes the FlowX SDK. Must be called in your application’s onCreate()fun init(context: Context, config: Config, customComponentsProvider: CustomComponentsProvider? = null, customStepperHeaderProvider: CustomStepperHeaderProvider? = null, customLoaderProvider: CustomLoaderProvider? = null, analyticsCollector: AnalyticsCollector? = null, onNewProcessStarted: NewProcessStartedHandler.Delegate? = null)
setAccessTokenUpdates the access tokenfun setAccessToken(accessToken: String?)
setupThemeSets up the theme to be used when rendering a processfun setupTheme(workspaceUuid: String, appearance: ThemeAppearance = ThemeAppearance.LIGHT, themeUuid: String, fallbackThemeJsonFileAssetsPath: String? = null, @MainThread onCompletion: () -> Unit)
changeLocaleSettingsChanges the current locale settings (i.e. locale and language)fun changeLocaleSettings(locale: Locale, language: String)
startProcessStarts a FlowX process instance, by returning a @Composable function where the process is rendered.fun startProcess(workspaceId: String, projectId: String, processName: String, params: JSONObject = JSONObject(), isModal: Boolean = false, onProcessEnded: (() -> Unit)? = null, closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null): @Composable () -> Unit
continueProcessContinues an existing FlowX process instance, by returning a @Composable function where the process is rendered.fun continueProcess(processUuid: String, isModal: Boolean = false, onProcessEnded: (() -> Unit)? = null, closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null): @Composable () -> Unit

Configuring the library

To configure the SDK, there are two things needed in the project’s application class:
  1. first, make it implement the FlowxOwner interface:
class MyApplication : Application(), FlowxOwner {
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() }
    // ...
}
  1. then, call the init method inside the onCreate() method:
fun init(
    context: Context,
    config: Config,
    customComponentsProvider: CustomComponentsProvider? = null,
    customStepperHeaderProvider: CustomStepperHeaderProvider? = null,
    customLoaderProvider: CustomLoaderProvider? = null,
    analyticsCollector: AnalyticsCollector? = null,
    onNewProcessStarted: NewProcessStartedHandler.Delegate? = null,
)

Parameters

NameDescriptionTypeRequirement
contextAndroid application ContextContextMandatory
configSDK configuration parametersai.flowx.android.sdk.api.ConfigMandatory
customComponentsProviderProvider for the @Composable custom componentsai.flowx.android.sdk.api.custom.components.CustomComponentsProvider?Optional. Defaults to null.
customStepperHeaderProviderProvider for the @Composable custom stepper header viewai.flowx.android.sdk.api.custom.stepper.CustomStepperHeaderProvider?Optional. Defaults to null.
customLoaderProviderProvider for the @Composable custom loader viewai.flowx.android.sdk.api.custom.loader.CustomLoaderProvider?Optional. Defaults to null.
analyticsCollectorCollector interface for SDK analytics eventsai.flowx.android.sdk.api.analytics.AnalyticsCollectorOptional. Defaults to null.
onNewProcessStartedCallback for when a new process was started as a consequence for executing a START_PROJECT actionai.flowx.android.sdk.api.NewProcessStartedHandler.DelegateOptional. Defaults to null.
• The custom components implementation is explained in its own section.
• The implementation for providing a custom view for the header of the Stepper component is detailed in its own section.
• The implementation for providing a custom loader is explained in its own section.
• Collecting analytics events from the SDK is explained in its own section.
• Handling the start of a new process while in a running process is explained in its own section.

Sample

class MyApplication : Application(), FlowxOwner {
    override val flowx: Lazy<Flowx> = lazy { Flowx.getInstance() }

    override fun onCreate() {
        super.onCreate()
        initFlowXSdk()
    }

    private fun initFlowXSdk() {
        Flowx.getInstance().init(
            context = applicationContext,
            config = object : Config {
                override val baseUrl = "URL to FlowX backend",
                override val imageBaseUrl = "URL to FlowX CMS Media Library",
                override val enginePath = "some_path",
                override val language = "en",
                override val locale = Locale.getDefault(),
                override val validators: Map<String, (String) -> Boolean>? = mapOf("exact_25_in_length" to { it.length == 25 }),
                override val logEnabled: Boolean get() = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE,
            },
            customComponentsProvider = object : CustomComponentsProvider {...},
            customStepperHeaderProvider = object : CustomStepperHeaderProvider {...},
            customLoaderProvider = object : CustomLoaderProvider {...},
            analyticsCollector = { event ->
                // Process / Send the event to some specialized Analytics platform
            },
            onNewProcessStarted = { processInstanceUuid ->
                // Send a broadcast message to notify the Activity currently displaying the running process.
                // The Activity should handle the broadcast to reload and display the newly started process identified by `processInstanceUuid`.
            }
        )
    }
}
The configuration properties that should be passed as Config data for the config parameter above are:
NameDescriptionTypeRequirement
baseUrlURL to connect to the FlowX back-end environmentStringMandatory
imageBaseUrlURL to connect to the FlowX Media Library module of the CMSStringMandatory
enginePathURL path segment used to identify the process engine serviceStringMandatory
languageThe language used for retrieving enumerations and substitution tagsStringOptional. Defaults to en.
localeThe locale used for date, number and currency formattingjava.util.LocaleOptional. Defaults to Locale.getDefault()
validatorsCustom validators for form elementsMap<String, (String) -> Boolean>?Optional.
logEnabledFlag indicating if logs should be printedBooleanOptional. Defaults to false

Custom validators

The custom 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, a custom validator named "exact_25_in_length" should be specified in the process definition.

Using the library

Authentication

To be able to use the SDK, authentication is required. Therefore, before calling any other method on the singleton instance, make sure that the access token is set by calling:
Flowx.getInstance().setAccessToken(accessToken = "your access token")
Whenever the access token changes based on your own authentication logic, it must be updated in the renderer by calling the setAccessToken method again.
Passing null or empty string ("") as an argument to the setAccessToken method clears the token

Theming

Prior setting up the theme, make sure the access token was set.
Check the authentication section for details.
To be able to use styled components while rendering a process, the theming mechanism must be invoked by calling the suspend-ing setupTheme(...) method over the singleton instance of the SDK:
suspend fun setupTheme(
    workspaceUuid: String,
    themeUuid: String,
    fallbackThemeJsonFileAssetsPath: String? = null,
    appearance: ThemeAppearance = ThemeAppearance.LIGHT,
    @MainThread onCompletion: () -> Unit
)

Parameters

NameDescriptionTypeRequirement
workspaceUuidUUID string identifier of the workspace that contains the theme to be loadedStringMandatory. Should not be empty
themeUuidUUID string of the theme configured in FlowX DesignerStringMandatory. Can be empty
fallbackThemeJsonFileAssetsPathAndroid asset relative path to the corresponding JSON file to be used as fallback, in case fetching the theme fails and there is no cached version availableString?Optional. Defaults to null
appearanceIndicator for the appearance of the theme (LIGHT, DARK)Flowx.ThemeAppearanceOptions. Defaults to Flowx.ThemeAppearance.LIGHT
onCompletion@MainThread invoked closure, called when setting up the theme completes() -> UnitMandatory
If the themeUuid parameter value is empty (""), no theme will be fetched, and the mechanism will rely only on the fallback file, if set.

If the fallbackThemeJsonFileAssetsPath parameter value is null, there will be no fallback mechanism set in place, meaning if fetching the theme fails, the redered process will have no style applied over it’s displayed components.
The SDK caches the fetched themes, so if a theme fetch fails, a cached version will be used, if available. Otherwise, it will use the file given as fallback.

Sample

viewModelScope.launch {
    Flowx.getInstance().setupTheme(
        workspaceUuid = "some workspace uuid string",
        themeUuid = "some uuid string",
        fallbackThemeJsonFileAssetsPath = "theme/a_fallback_theme.json",
        appearance = Flowx.ThemeAppearance.LIGHT,
    ) {
        // theme setup complete
        // do specific logic
    }
}
The fallbackThemeJsonFileAssetsPath always search for files under your project’s assets/ directory, meaning the example parameter value is translated to file://android_asset/theme/a_fallback_theme.json before being evaluated.
Do not start or resume a process before the completion of the theme setup mechanism.

Changing current locale settings

The current locale and language can be also changed after the initial setup, by calling the changeLocaleSettings function:
fun changeLocaleSettings(locale: Locale, language: String)

Parameters

NameDescriptionTypeRequirement
localeThe new localejava.util.LocaleMandatory
languageThe code for the new languageStringMandatory
Do not change the locale or the language while a process is rendered.
The change is successful only if made before starting or resuming a process.

Sample

Flowx.getInstance().changeLocaleSettings(locale = Locale("en", "US"), language = "en")
The Locale satisfies the IETF BCP 47 standard for representing language and country/region codes.

More information regarding the standard can be found by reading RFC 4647 “Matching of Language Tags” and RFC 5646 “Tags for Identifying Languages”.

An example of BCP 47 is en-US (language code en and country US).

Start a FlowX process

Prior starting a process, make sure the authentication and theming were correctly set up
After performing all the above steps and all the prerequisites are fulfilled, a new instance of a FlowX process can be started, by using the startProcess function:
fun startProcess(
    workspaceId: String,
    projectId: String,
    processName: String,
    params: JSONObject = JSONObject(),
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit

Parameters

NameDescriptionTypeRequirement
workspaceIdThe id of the workspace that contains the project and process to be startedStringMandatory
projectIdThe id of the project containing the process to be startedStringMandatory
processNameThe name of the processStringMandatory
paramsThe starting params for the process, if anyJSONObjectOptional. If omitted, if defaults to JSONObject()
isModalFlag indicating whether the process can be closed at anytime by tapping the top-right close buttonBooleanOptional. It defaults to false.
onProcessEndedLambda function where you can do additional processing when the started process ends(() -> Unit)?Optional. It defaults to null.
closeModalFuncLambda function where you should handle closing the process when isModal flag is true(CloseModalProcessScope.(processName: String) -> Unit)?Optional. It defaults to null.
The returned @Composable function must be included in its own Activity, which is part of (controlled and maintained by) the container application.

This wrapper activity must display only the @Composable returned from the SDK (i.e. it occupies the whole activity screen space).

Sample

class ProcessActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
        setContent {
            Flowx.getInstance().startProcess(
                workspaceId = "your workspace id",
                projectId = "your project id",
                processName = "your process name",
                params: JSONObject = JSONObject(),
                isModal = true,
                onProcessEnded = {
                    // NOTE: possible processing could involve doing something in the container app (i.e. navigating to a different screen)
                },
                closeModalFunc = { processName ->
                    // NOTE: possible handling could involve doing something differently based on the `processName` value
                },
            ).invoke()
        }
    }
    ...
}

Resume a FlowX process

Prior resuming process, make sure the authentication and theming were correctly set up
To resume an existing instance of a FlowX process, after fulfilling all the prerequisites, use the continueProcess function:
fun continueProcess(
    processUuid: String,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit

Parameters

NameDescriptionTypeRequirement
processUuidThe UUID string of the processStringMandatory
isModalFlag indicating whether the process can be closed at anytime by tapping the top-right close buttonBooleanOptional. It defaults to false.
onProcessEndedLambda function where you can do additional processing when the continued process ends(() -> Unit)?Optional. It defaults to null.
closeModalFuncLambda function where you should handle closing the process when isModal flag is true(CloseModalProcessScope.(processName: String) -> Unit)?Optional. It defaults to null.
The returned @Composable function must be included in its own Activity, which is part of (controlled and maintained by) the container application.

This wrapper activity must display only the @Composable returned from the SDK (i.e. it occupies the whole activity screen space).

Sample

class ProcessActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
        setContent {
            Flowx.getInstance().continueProcess(
                processUuid = "some process UUID string",
                isModal = true,
                onProcessEnded = {
                    // NOTE: possible processing could involve doing something in the container app (i.e. navigating to a different screen)
                },
                closeModalFunc = { processName ->
                    // NOTE: possible handling could involve doing something differently based on the `processName` value
                },
            ).invoke()
        }
    }
    ...
}

closeModalFunc parameter

The closeModalFunc parameter is a function defined within the CloseModalProcessScope context. This gives the ability to query for substitution tags or media library items in order to use them when handling this callback (i.e. showing an snackbar or an alert).
interface CloseModalProcessScope {
    fun replaceSubstitutionTag(key: String): String
    fun getMediaResourceUrl(key: String): String?
}

Get a substitution tag value by key

fun replaceSubstitutionTag(key: String): String
All substitution tags will be retrieved by the SDK before starting the process and will be stored in memory. Whenever the container app needs a substitution tag value for populating the UI of the custom components, it can request the substitution tag, through the CustomComponentScope context, using the method above, by providing the 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

fun getMediaResourceUrl(key: String): String?
All media items will be retrieved by the SDK before starting the process and will be stored in memory. Whenever the container app needs a media item url for populating the UI of the custom components, it can request the url, through the CustomComponentScope context, using the method above, by providing the key. It returns the URL string of the media resource, or null, if not found.

Sample

setContent {
    var closeModalProcessScope by remember { mutableStateOf<CloseModalProcessScope?>(null) }
    val showCloseModalProcessAlert = remember { mutableStateOf(false) }

    Flowx.getInstance().startProcess(
        workspaceId = "your workspace id",
        projectId = "your project id",
        processName = "your process name",
        isModal = true,
        onProcessEnded = { ... },
        onCloseProcessModalFunc = { processName ->
            closeModalProcessScope = this
            showCloseModalProcessAlert.value = true
        },
    ).invoke()

    closeModalProcessScope?.CloseModalProcessConfirmAlert(show = showCloseModalProcessAlert)
}

@Composable
fun CloseModalProcessScope.CloseModalProcessConfirmAlert(show: MutableState<Boolean>) {
    if (show.value) {
        AlertDialog(
            onDismissRequest = {},
            title = null,
            text = {
                Text(this@CloseModalProcessConfirmAlert.replaceSubstitutionTag("@@close_message")) // IMPORTANT: call `replaceSubstitutionTag` using the `CloseModalProcessScope` context
            },
            confirmButton = { ... },
            dismissButton = {
                Button(onClick = { show.value = false }) {
                    Text("Cancel")
                }
            }
        )
    }
}

Custom components

The container application should decide which custom component view to provide using the componentIdentifier configured in the UI designer. A custom component receives data to populate the view and actions available to execute, as described below.
It can also be validated and provide data back into the process when executing an action.
To handle custom components, an implementation of the CustomComponentsProvider interface should be passed as a parameter when initializing the SDK:
interface CustomComponentsProvider {
    fun provideCustomComponent(componentIdentifier: String): CustomComponent?
}

Sample

class FxCustomComponentsProvider : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            "myCustomComponent" -> object : CustomComponent {...}
            else -> null
        }
}

CustomComponent

The implementation for providing a custom component is based on creating and binding a user defined @Composable function, through the CustomComponent interface:
interface CustomComponent {
    /**
     * Returns the [Composable]s for every custom component identifier defined in the FlowX Designer
     */
    val composable: @Composable CustomComponentScope.() -> Unit

    /**
     * This will be called when data is available for the custom component i.e. when the
     * User Task that contains the custom component is displayed.
     *
     * @param data used to populate the custom component
     */
    fun populateUi(data: Any?)

    /**
     * This will be called when actions are available for the custom component i.e. when the
     * User Task that contains the custom component is displayed.
     *
     * @param actions that need to be attached to the custom component (e.g. onClick events)
     */
    fun populateUi(actions: Map<String, CustomComponentAction>)

    /**
     * This will be called when executing an action, when the platform needs to know if the specified/marked components are valid.
     * Defaults to `true`.
     */
    fun validate(): Boolean = true

    /**
     * This will be called when executing an action, on computing the data to be sent as body on the network request.
     * Returning `null` (i.e. default) means it does not contribute with any data to be sent.
     */
    fun saveData(): JSONObject? = null
}
The value for the data parameter received in the populateUi(data: Any?) could be:
  • Boolean
  • String
  • java.lang.Number
  • org.json.JSONObject
  • org.json.JSONArray
The appropriate way to check and cast the data accordingly to the needs must belong to the implementation details of the custom component.
Both validation and providing data back into process are optional, and, based on the needs, it may be included in the implementation or not.

CustomComponentScope

The composable property of the CustomComponent is a @Composable function which may be defined and run only within the context of a CustomComponentScope receiver.
val composable: @Composable CustomComponentScope.() -> Unit
interface CustomComponentScope {
    fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
    fun replaceSubstitutionTag(key: String): String
    fun getMediaResourceUrl(key: String): String?
    suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
}
This allows calling predefined SDK methods for executing actions, querying for substitution tags, media resource URLs or obtaining enumerations data, directly from the custom component through the scope itself.

Execute action

The custom components which the container app provides may contain FlowX actions available for execution.

These actions are received through the actions parameter of the populateUi(actions: Map<String, CustomComponentAction>) method.

In order to run an action (i.e. on a click of a button in the custom component) you need to call the executeAction method, through the CustomComponentScope context:
fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
Parameters
NameDescriptionTypeRequirement
actionAction object extracted from the actions received in the custom componentai.flowx.android.sdk.api.custom.components.CustomComponentActionMandatory
paramsParameters needed to execute the actionJSONObject?Optional. It defaults to null

Get a substitution tag value by key

fun replaceSubstitutionTag(key: String): String
All substitution tags will be retrieved by the SDK before starting the process and will be stored in memory. Whenever the container app needs a substitution tag value for populating the UI of the custom components, it can request the substitution tag, through the CustomComponentScope context, using the method above, by providing the 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

fun getMediaResourceUrl(key: String): String?
All media items will be retrieved by the SDK before starting the process and will be stored in memory. Whenever the container app needs a media item url for populating the UI of the custom components, it can request the url, through the CustomComponentScope context, using the method above, by providing the key. It returns the URL string of the media resource, or null, if not found.

Obtain enumeration data

suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
Whenever the container app needs an enumeration data for populating the UI of the custom components, it can request the url, through the CustomComponentScope context, using the method above, by providing the name (and the parentName, if there’s a hierarchy defined and the desired enumeration data (name is child of parentName). It returns the enumeration data, as an FxEnumeration object, or null, if not found.
interface FxEnumeration {
    val name: String
    val items: List<Item>
    val parentName: String?

    interface Item {
        val code: String
        val content: String?
        val childNomenclatorName: String?
        val order: Int
    }
}

Sample

Among multiple existing custom components, there may be one that:
  • allows the input of a value representing an age
  • the value should be validated (e.g. to be at least 35 years old)
  • the value will be passed back into the process
  • execute an action, through the CustomComponentScope context, to skip setting the age
class FxCustomComponentsProvider : CustomComponentsProvider {
    override fun provideCustomComponent(componentIdentifier: String): CustomComponent? =
        when (componentIdentifier) {
            when (componentIdentifier) {
                "other-custom-component-identifier" -> OtherCustomComponent()
                "age" -> AgeCustomComponent()
                else -> null
            }
        }
}

private class AgeCustomComponent() : CustomComponent {
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null)
    private var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel = AgeViewModel(data = data, actions = actions)

    override val composable: @Composable CustomComponentScope.() -> Unit
        get() = @Composable {
            Age(viewModel = viewModel)
        }

    override fun populateUi(data: Any?) {
        this@AgeCustomComponent.data.update { _ -> data }
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        this@AgeCustomComponent.actions.apply {
            clear()
            putAll(actions)
        }
    }

    override fun validate(): Boolean = viewModel.isValid()

    override fun saveData(): JSONObject? = viewModel.buildDataToSave()
}

@Composable
private fun CustomComponentScope.Age(viewModel: AgeViewModel) {
    viewModel.setFlowxScope(this@Age) // IMPORTANT: keep a reference to the custom context/scope in order to access the available predefined SDK methods

    val age by viewModel.ageFlow.collectAsState()
    val error by viewModel.errorFlow.collectAsState()
    val isError by remember(error) { mutableStateOf(error.isNotBlank()) }

    Column {
        OutlinedTextField(
            value = age,
            onValueChange = { viewModel.updateAge(it) },
            modifier = Modifier.fillMaxWidth(),
            label = { Text("Age") },
        )

        if (isError) {
            Text(
                modifier = Modifier.fillMaxWidth(),
                text = error,
                style = TextStyle(fontSize = 12.sp),
                color = Color.Red,
                textAlign = TextAlign.Start,
            )
        }

        TextButton(
            onClick = { viewModel.executeSkipAction() }
        ) {
            Text(text = "Skip")
        }
    }
}

private class AgeViewModel(
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    private val actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope // IMPORTANT: keeps the custom context/scope which allows to call the available predefined methods exposed to custom component

    private val _ageFlow = MutableStateFlow("")
    val ageFlow: StateFlow<String> = _ageFlow.asStateFlow()

    private val _error = MutableStateFlow("")
    val errorFlow: StateFlow<String> = _error.asStateFlow()

    fun updateAge(text: String) {
        _ageFlow.value = text
    }

    fun setFlowxScope(scope: CustomComponentScope) {
        flowxScope = scope
    }

    fun isValid(): Boolean = ageFlow.value.toIntOrNull().let {
        when {
            it == null -> false.also { _error.update { "Unrecognized format" } }
            it < 35 -> false.also { _error.update { "You have to be at least 35 years old" } }
            else -> true.also { _error.update { "" } }
        }
    }

    fun buildDataToSave(): JSONObject? = ageFlow.value.takeUnless { it.isBlank() }
        ?.let {
            JSONObject(
                """
            {
                "app": {
                    "age": "$it"
                }
            }
            """.trimIndent()
            )
        }

    fun executeSkipAction() {
        actions["skipAction"]?.let {
            if (this@AgeViewModel::flowxScope.isInitialized) { // IMPORTANT: if the custom context/scope was initialized, the action can be safely executed
                flowxScope.executeAction(
                    action = it,
                    params = JSONObject() // e.g. JSONObject("{\"someParameter\": \"someValue\"}")
                )
            }
        } ?: println("AgeCustomComponent: `skipAction` action was not found")
    }
}

private class OtherCustomComponent() : CustomComponent {
    override val composable: @Composable (CustomComponentScope.() -> Unit)
        get() = @Composable {
            /* add some @Composable implementation */
        }

    override fun populateUi(data: Any?) {
        // extract the necessary data to be used for displaying the custom components
    }

    override fun populateUi(actions: Map<String, CustomComponentAction>) {
        // extract the available actions that may be executed from the custom components
    }

    // Optional override, defaults to `true`.
    // Here one can pass validation logic from viewModel (e.g. by calling `viewModel.isValid()`)
    override fun validate(): Boolean = true

    // Optional override, defaults to `null`.
    // Here one can pass data to save from viewModel (e.g. by calling `viewModel.getDataToSave()`)
    override fun saveData(): JSONObject? = null
}

Custom header view for the STEPPER component

The container application can opt for providing a custom view in order to be used, for all the Stepper components, as a replacement for the built-in header.
The custom view receives data to populate its UI, as described below.
To provide a custom header for the Stepper, an implementation of the CustomStepperHeaderProvider interface should be passed as a parameter when initializing the SDK:
interface CustomStepperHeaderProvider {
    fun provideCustomStepperHeader(): CustomStepperHeader?
}

Sample

class FxCustomStepperHeaderProvider : CustomStepperHeaderProvider {
    override fun provideCustomStepperHeader(): CustomStepperHeader? {
        return object : CustomStepperHeader {...}
    }
}

CustomStepperHeader

To provide the custom header view as a @Composable function, you have to implement the CustomStepperHeader interface:
interface CustomStepperHeader {
    /**
     * Returns the [Composable]s used to render the stepper header.
     * The received argument contains the stepper header necessary data to render the view.
     */
    val composable: @Composable (data: Data) -> Unit

    interface Data {
        // title for the current step; can be empty or null
        val stepTitle: String?
        // title for the current selected substep; optional;
        // can be empty ("") if not defined or `null` if currently there is no selected substep
        val substepTitle: String?
        // 1-based index of the current step
        val step: Int
        // total number of steps
        val totalSteps: Int
        // 1-based index of the current substep; can be `null` when there are no defined substeps
        val substep: Int?
        // total number of substeps in the current step; can be `null` or `0`
        val totalSubsteps: Int?
    }
}

Sample

override fun provideCustomStepperHeader(): CustomStepperHeader? {
    return object : CustomStepperHeader {
        override val composable: @Composable ((CustomStepperHeader.Data) -> Unit)
            get() = @Composable { data ->
                /* add some @Composable implementation which displays the `data` */
            }
    }
}

Custom loaders

The container application can decide to provide custom loaders to be displayed at certain moments based on a given predefined actionName.
To provide custom loaders, an implementation of the CustomLoaderProvider interface should be passed as a parameter when initializing the SDK:
interface CustomLoaderProvider {
    fun provideCustomLoader(actionName: String?): CustomLoader?
}
The possible values for the actionName parameter are:
  • startProcess - received for overriding the loader displayed when starting a new process
  • reloadProcess - received for overriding the loader displayed when resuming an existing process
  • whatever string value representing the name of an action as defined at process definition time - received for overriding the loader displayed while that action is executed
Returning an implementation of a CustomLoader replaces the built-in platform loader with the provided one for the specified use cases.

Returning null keeps the built-in platform loader for the specified use cases.

CustomLoader

The implementation for providing a custom loader is based on creating and binding a user defined @Composable function, through the CustomLoader interface:
interface CustomLoader {
    val composable: @Composable CustomLoaderScope.() -> Unit
}

CustomLoaderScope

The composable property of the CustomLoader is a @Composable function which may be defined and run only within the context of a CustomLoaderScope receiver.
val composable: @Composable CustomLoaderScope.() -> Unit
interface CustomLoaderScope {
    fun replaceSubstitutionTag(key: String): String
    fun getMediaResourceUrl(key: String): String?
}
This allows calling predefined SDK methods for querying for substitution tags and media resource URLs directly from the custom loader through the scope itself.

Sample

class FxCustomLoaderProvider : CustomLoaderProvider {
    override fun provideCustomLoader(actionName: String?): CustomLoader? =
        when (actionName) {
            "startProcess" -> MyCustomLoader(backgroundColor = Color.Black.copy(alpha = 0.38f), indicatorColor = Color.Red)
            "reloadProcess" -> MyCustomLoader(backgroundColor = Color.Yellow.copy(alpha = 0.38f), indicatorColor = Color.Green)
            "action1" -> ActionCustomLoader()
            "action2" -> ComplexCustomLoader()
            else -> null
        }
}

class MyCustomLoader(val backgroundColor: Color, val indicatorColor: Color) : CustomLoader {
    override val composable: @Composable (CustomLoaderScope.() -> Unit)
        get() = @Composable {
            Box(
                modifier = Modifier
                    .fillMaxSize()
                    .background(color = backgroundColor),
                contentAlignment = Alignment.Center,
            ) {
                CircularProgressIndicator(color = indicatorColor)
                BackHandler(enabled = true) {} // block back navigation
            }
        }
}

class ActionCustomLoader() : CustomLoader {...}

class ComplexCustomLoader() : CustomLoader {
    private val animatedViewModel = AnimatedLoaderViewModel(...)
    override val composable: @Composable (CustomLoaderScope.() -> Unit)
        get() = @Composable {
            AnimatedLoader(viewModel = animatedViewModel)
        }
}

@Composable
private fun CustomLoaderScope.AnimatedLoader(
    viewModel: AnimatedLoaderViewModel
) {
    viewModel.setFlowxScope(this@AnimatedLoader) // IMPORTANT: keep a reference to the custom context/scope in order to access the available predefined SDK methods

    val state by viewModel.loaderState.collectAsStateWithLifecycle()

    Box {
        // use state to build what is to be displayed
    }
}

private class AnimatedLoaderViewModel(...) : ViewModel() {
    private lateinit var flowxScope: CustomLoaderScope // IMPORTANT: keeps the custom context/scope which allows to call the available predefined methods exposed to custom component

    val loaderState: StateFlow<AnimatedLoaderState?> =
        someData
            .process {
                if (this@AnimatedLoaderViewModel::flowxScope.isInitialized) { // IMPORTANT: if the custom context/scope was initialized, the substitution tag can be safely queried
                    flowxScope.replaceSubstitutionTag(it)
                } else {
                    it
                }
            }
            .stateIn(...)

    fun setFlowxScope(scope: CustomLoaderScope) {
        flowxScope = scope
    }
}

Collecting analytics events

To be able to collect analytics events from the SDK, an implementation for the AnalyticsCollector functional interface may be provided when initializing the SDK:
fun interface AnalyticsCollector {
    fun onEvent(event: Event)
}
There are two types of events, Screen and Action, both of them containing some Data and an optional CustomPayload, as defined at process definition time. The Event is structured like this:
sealed interface Event {
    interface Screen : Event {
        val data: Screen.Data

        interface Data {
            val value: String
            val customPayload: CustomPayload?
        }
    }

    interface Action : Event {
        val data: Action.Data

        interface Data {
            val value: String
            val screen: String?
            val component: String?
            val label: String?
            val customPayload: CustomPayload?
        }
    }

    sealed interface CustomPayload {
        interface Object : CustomPayload {
            val data: JSONObject
        }

        interface Array : CustomPayload {
            val data: JSONArray
        }
    }
}

Sample

The implementation can be passed as a lambda, like:
analyticsCollector = { event ->
    // do whatever is needed (e.g. log the event)
    when (it) {
        is Event.Screen -> {
            val customPayload: String? =
                when (val payload = it.data.customPayload) {
                    is Event.CustomPayload.Object -> payload.data.toString()
                    is Event.CustomPayload.Array -> payload.data.toString()
                    else -> null
                }
            Log.i("Analytics", "Event.Screen(value = ${it.data.value}, customPayload = $customPayload)")
        }

        is Event.Action -> {
            val customPayload: String? =
                when (val payload = it.data.customPayload) {
                    is Event.CustomPayload.Object -> payload.data.toString()
                    is Event.CustomPayload.Array -> payload.data.toString()
                    else -> null
                }
            Log.i("Analytics", "Event.Action(value = ${it.data.value}, screen = ${it.data.screen}, component = ${it.data.component}, label = ${it.data.label}, customPayload = $customPayload)")
        }
    }
}
The value property represents the identifier set in the process definition.For action type events there are some additional properties provided:
  • component - The type of component triggering the action
  • label - The label of the component, if available. (E.g. title of a button or label of a form element)
  • screen - The identifier of the screen containing the component, if set
The customPayload is defined at process definition time, and then processed inside the platform before sending it to being collected.

Handling “Start of a new process”

When an action of type START_PROJECT is executed, the onNewProcessStarted lambda provided in the Flowx.getInstance().init(...) function is invoked. This callback provides the UUID of the newly started process, which can be used to resume the process by calling the Flowx.getInstance().continueProcess(...) method. It is the responsibility of the container application’s developer to implement the necessary logic for displaying the appropriate UI for the newly started process.

Sample

One way to handle this is to send a broadcast message to notify the Activity currently displaying the running process. The Activity should handle the broadcast to reload and display the newly started process identified by processInstanceUuid (received in the broadcast intent).
Flowx.getInstance().init(
    ...
    onNewProcessStarted = { processInstanceUuid ->
        applicationContext.sendBroadcast(
            Intent("some.intent.filter.indentifier").apply {
                putExtra("processInstanceUuid", processInstanceUuid)
                setPackage("your.application.package")
            }
        )
    }
    ...
)

class ProcessActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...

        setContent {
            val yourBroadcastReceiver = remember {
                YourBroadcastReceiver(handler = { processInstanceUuid -> /* do your own logic to refresh `ProcessContent()` */ })
            }

            val context = LocalContext.current
            LifecycleStartEffect(true) {
                ContextCompat.registerReceiver(context.applicationContext, yourBroadcastReceiver, IntentFilter("some.intent.filter.indentifier"), ContextCompat.RECEIVER_NOT_EXPORTED)
                onStopOrDispose {
                    runCatching {
                        context.applicationContext.unregisterReceiver(yourBroadcastReceiver)
                    }
                }
            }

            ProcessContent()
        }
    }

    @Composable
    private fun ProcessContent(...) {...}
}

class YourBroadcastReceiver(private val handler: (String) -> Unit) : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        intent?.extras?.getString("processInstanceUuid")?.let { processUuid -> handler.invoke(processUuid) }
    }
}

Known issues