Android SDK

dependencyResolutionManagement {
    ...
    repositories {
        ...
        maven {
            url = uri("https://nexus-jx.dev.rd.flowx.ai/repository/flowx-maven-releases/")
            credentials {
                username = "your_username"
                password = "your_password"
            }
        }
    }
}

dependencies {
    ...
    implementation("ai.flowx.android:sdk:<version>")
    ...
}

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

fun init(
    context: Context,
    config: Config,
    customComponentsProvider: CustomComponentsProvider? = null,
    customStepperHeaderProvider: CustomStepperHeaderProvider? = null,
    customLoaderProvider: CustomLoaderProvider? = null,
    analyticsCollector: AnalyticsCollector? = null,
    onNewProcessStarted: NewProcessStartedHandler.Delegate? = null,
)

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 organizationId: String = "organization id"
                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`.
            }
        )
    }
}

Flowx.getInstance().setAccessToken(accessToken = "your access token")

suspend fun setupTheme(
    workspaceUuid: String,
    themeUuid: String,
    fallbackThemeJsonFileAssetsPath: String? = null,
    appearance: ThemeAppearance = ThemeAppearance.LIGHT,
    @MainThread onCompletion: () -> Unit
)

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
    }
}

fun changeLocaleSettings(locale: Locale, language: String)

Flowx.getInstance().changeLocaleSettings(locale = Locale("en", "US"), language = "en")

fun startProcess(
    workspaceId: String,
    projectId: String,
    processName: String,
    params: JSONObject? = null,
    isModal: Boolean = false,
    onProcessStarted: ((String) -> Unit)? = null,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit

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,
                onProcessStarted = { processInstanceUuid ->
                    // NOTE: possible processing could involve doing something based on the `processInstanceUuid` value received as argument
                },
                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()
        }
    }
    ...
}

fun continueProcess(
    processUuid: String,
    isModal: Boolean = false,
    onProcessEnded: (() -> Unit)? = null,
    closeModalFunc: (CloseModalProcessScope.(processName: String) -> Unit)? = null,
): @Composable () -> Unit

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()
        }
    }
    ...
}

interface CloseModalProcessScope {
    fun replaceSubstitutionTag(key: String): String
    fun getMediaResourceUrl(key: String): String?
}

fun replaceSubstitutionTag(key: String): String

fun getMediaResourceUrl(key: String): String?

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,
        onProcessStarted= { ... },
        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")
                }
            }
        )
    }
}

fun startUiFlow(
    workspaceId: String,
    projectId: String,
    uiFlowName: String,
    params: JSONObject? = null,
): @Composable () -> Unit

class UiFlowActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
        setContent {
            Flowx.getInstance().startUiFlow(
                workspaceId = "your workspace id",
                projectId = "your project id",
                uiFlowName = "your ui flow name",
                params = JSONObject(),
            ).invoke()
        }
    }
    ...
}

interface CustomComponentsProvider {
    fun provideCustomComponent(componentIdentifier: String): CustomComponent?
}

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

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
}

val composable: @Composable CustomComponentScope.() -> Unit

interface CustomComponentScope {
    fun executeAction(action: CustomComponentAction, params: JSONObject? = null)
    fun executeUploadAction(action: CustomComponentAction, fileUri: Uri, mimeType: String? = null, params: JSONObject? = null)
    fun replaceSubstitutionTag(key: String): String
    fun getMediaResourceUrl(key: String): String?
    suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?
}

fun executeAction(action: CustomComponentAction, params: JSONObject? = null)

fun executeUploadAction(action: CustomComponentAction, fileUri: Uri, mimeType: String? = null, params: JSONObject? = null)

class FileUploadCustomComponent : CustomComponent {
    var actions: MutableMap<String, CustomComponentAction> = mutableMapOf()

    private val viewModel: FileUploadViewModel by lazy {
        FileUploadViewModel(actions = actions)
    }

    override val composable: @Composable CustomComponentScope.() -> Unit =
        @Composable {
            val rememberedViewModel = remember { viewModel }
            FileUpload(viewModel = rememberedViewModel)
        }

    override fun populateUi(data: Any?) { ... }

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

@Composable
private fun CustomComponentScope.FileUpload(viewModel: FileUploadViewModel) {
    viewModel.setFlowxScope(this@FileUpload)
    val context = LocalContext.current
    val openDocumentLauncher =
        rememberLauncherForActivityResult(ActivityResultContracts.OpenDocument()) { uri ->
            uri?.let { viewModel.executeUploadAction(fileUri = it, mimeType = it.mimeType(context)) }
            Flowx.getInstance().configureUpdateState(enabled = true) // IMPORTANT: restore the SDK internal update mechanism after selecting a file to be uploaded
        }

    Column(
        modifier = Modifier.fillMaxWidth(),
        horizontalAlignment = Alignment.CenterHorizontally,
    ) {
        Button(
            onClick = {
                Flowx.getInstance().configureUpdateState(enabled = false) // IMPORTANT: disable SDK internal update mechanism while selecting a file to be uploaded
                openDocumentLauncher.launch(listOf("application/pdf").toTypedArray()) // select PDF files only
            }
        ) {
            Text(text = "Upload File")
        }
    }
}

private class FileUploadViewModel(
    private var actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    private lateinit var flowxScope: CustomComponentScope

    fun executeUploadAction(fileUri: Uri, mimeType: String?) {
        actions["uploadFile"]?.let { action ->
            if (this@FileUploadViewModel::flowxScope.isInitialized) {
                flowxScope.executeUploadAction(
                    action = action,
                    params = null,
                    fileUri = fileUri,
                    mimeType = mimeType,
                )
            }
        }
    }

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

private fun Uri.mimeType(context: Context): String? = context.contentResolver.getType(this)

fun replaceSubstitutionTag(key: String): String

fun getMediaResourceUrl(key: String): String?

suspend fun getEnumeration(name: String, parentName: String? = null): FxEnumeration?

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
    }
}

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
}

interface CustomStepperHeaderProvider {
    fun provideCustomStepperHeader(): CustomStepperHeader?
}

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

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?
    }
}

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` */
            }
    }
}

interface CustomLoaderProvider {
    fun provideCustomLoader(loaderType: CustomLoaderProvider.LoaderType?): CustomLoader?
}

interface LoaderType {
    interface StartProcess : LoaderType
    interface ReloadProcess : LoaderType
    interface Action : LoaderType { val name: String }
    interface Upload : LoaderType { val name: String }
}

interface CustomLoader {
    val composable: @Composable CustomLoaderScope.() -> Unit
}

val composable: @Composable CustomLoaderScope.() -> Unit

interface CustomLoaderScope {
    fun replaceSubstitutionTag(key: String): String
    fun getMediaResourceUrl(key: String): String?
}

class FxCustomLoaderProvider : CustomLoaderProvider {
    override fun provideCustomLoader(loaderType: CustomLoaderProvider.LoaderType?): CustomLoader? =
        when (loaderType) {
            is CustomLoaderProvider.LoaderType.StartProcess -> MyCustomLoader(backgroundColor = Color.Black.copy(alpha = 0.38f), indicatorColor = Color.Red)
            is CustomLoaderProvider.LoaderType.ReloadProcess -> MyCustomLoader(backgroundColor = Color.Yellow.copy(alpha = 0.38f), indicatorColor = Color.Green)
            is CustomLoaderProvider.LoaderType.Action -> {
                when (loaderType.name) {
                    "action1" -> ActionCustomLoader()
                    "action2" -> ComplexCustomLoader()
                    else -> null
                }
            }
            is CustomLoaderProvider.LoaderType.Upload -> {
                when (loaderType.name) {
                    "upload1" -> ActionCustomLoader()
                    "upload2" -> ComplexCustomLoader()
                    else -> null
                }
            }
            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
    }
}

fun interface AnalyticsCollector {
    fun onEvent(event: Event)
}

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
        }
    }
}

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)")
        }
    }
}

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) }
    }
}