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:android-sdk:4.0.24")
    ...
}

fun init(
    context: Context,
    config: SdkConfig,
    accessTokenProvider: AccessTokenProvider? = null,
    customComponentsProvider: CustomComponentsProvider? = null,
    customStepperHeaderProvider: CustomStepperHeaderProvider? = null,
    analyticsCollector = null,
    onNewProcessStarted = null,
)

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        initFlowXSdk()
    }

    private fun initFlowXSdk() {
        FlowxSdkApi.getInstance().init(
            context = applicationContext,
            config = SdkConfig(
                baseUrl = "URL to FlowX backend",
                imageBaseUrl = "URL to FlowX CMS Media Library",
                enginePath = "some_path",
                language = "en",
                locale = Locale.getDefault(),
                validators = mapOf("exact_25_in_length" to { it.length == 25 }),
                enableLog = false,
            ),
            accessTokenProvider = null, // null by default; can be set later, depending on the existing authentication logic
            customComponentsProvider = object : CustomComponentsProvider {...},
            customStepperHeaderProvider = object : CustomStepperHeaderProvider {...},
            analyticsCollector = { event ->
                when (event) {
                    is Event.Screen -> Log.i("Analytics", "Event.Screen(value = ${event.data.value})")
                    is Event.Action -> Log.i("Analytics", "Event.Action(value = ${event.data.value}, screen = ${event.data.screen}, component = ${event.data.component}, label = ${event.data.label})")
                }
            },
            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`.
            }
        )
    }
}

FlowxSdkApi.getInstance().setAccessTokenProvider(accessTokenProvider = { "your access token" })

fun interface AccessTokenProvider {
    fun get(): String
}

suspend fun setupTheme(
    themeUuid: String,
    fallbackThemeJsonFileAssetsPath: String? = null,
    @MainThread onCompletion: () -> Unit
)

viewModelScope.launch {
    FlowxSdkApi.getInstance().setupTheme(
        themeUuid = "some uuid string",
        fallbackThemeJsonFileAssetsPath = "theme/a_fallback_theme.json",
    ) {
        // theme setup complete
        // do specific logic
    }
}

fun changeLocaleSettings(locale: Locale, language: String)

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

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

class ProcessActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
        setContent {
            FlowxSdkApi.getInstance().startProcess(
                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()
        }
    }
    ...
}

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

class ProcessActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        ...
        setContent {
            FlowxSdkApi.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 CustomComponentsProvider {
    fun provideCustomComposableComponent(): CustomComposableComponent?
}

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComposableComponent(): CustomComposableComponent? {
        return object : CustomComposableComponent {...}
    }
}

interface CustomComposableComponent {
    fun provideCustomComposable(componentIdentifier: String): CustomComposable
}

interface CustomComposable {
    @Deprecated(message = "Will be removed in future releases")
    val isDefined: Boolean // always MUST return `true`

    // `@Composable` definitions for the custom components that can be handled
    val composable: @Composable () -> Unit

    /**
     * Called when the 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?)

    /**
     * Called when the 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 from a FlowX.AI UI Component, 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 from a FlowX.AI UI Component, 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
}

class CustomComponentsProviderImpl : CustomComponentsProvider {
    override fun provideCustomComposableComponent(): CustomComposableComponent? {
        return object : CustomComposableComponent {
            override fun provideCustomComposable(componentIdentifier: String): CustomComposable? =
                when (componentIdentifier) {
                    "other-custom-component-identifier" -> OtherCustomComposable().invoke()
                    "age" -> AgeCustomComposable().invoke()
                    else -> null
                }
        }
    }
}

private class AgeCustomComposable() {
    operator fun invoke(): CustomComposable = object : CustomComposable {
        val data: MutableStateFlow<Any?> = MutableStateFlow(null)
        var actions: Map<String, CustomComponentAction> = emptyMap()

        private val viewModel: AgeViewModel by lazy {
            AgeViewModel(data = data,actions = actions)
        }

        override val isDefined: Boolean = true // always MUST return `true`

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

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

        override fun populateUi(actions: Map<String, CustomComponentAction>) {
            this.actions = actions
        }

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

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

@Composable
private fun Age(
    viewModel: AgeViewModel = viewModel<AgeViewModel>()
) {
    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,
            )
        }
    }
}

class AgeViewModel(
    private val data: MutableStateFlow<Any?> = MutableStateFlow(null),
    private val actions: Map<String, CustomComponentAction> = emptyMap(),
) : ViewModel() {
    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 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()
        )
    }
}

class OtherCustomComposable() {
    operator fun invoke(): CustomComposable = object : CustomComposable {
        // deprecated property: will be removed in future releases.
        override val isDefined: Boolean = true // always MUST return `true`

        override val composable: @Composable () -> Unit = @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
    }
}

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

fun replaceSubstitutionTag(key: String): String

fun getMediaResourceUrl(key: String): String?

interface CustomStepperHeaderProvider {
    fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader?
}

class CustomStepperHeaderProviderImpl : CustomStepperHeaderProvider {
    override fun provideCustomComposableStepperHeader(): CustomComposableStepperHeader? {
        return object : CustomComposableStepperHeader {...}
    }
}

interface CustomComposableStepperHeader {
    fun provideComposableStepperHeader(): ComposableStepperHeader
}

interface ComposableStepperHeader {
    /**
     * `@Composable` definition for the custom header view
     * The received argument contains the stepper header necessary data to render the view.
     */
    val composable: @Composable (data: CustomStepperHeaderData) -> Unit
}

interface CustomStepperHeaderData {
    // 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 provideComposableStepperHeader(): ComposableStepperHeader? {
    return object : ComposableStepperHeader {
        override val composable: @Composable (data: CustomStepperHeaderData) -> Unit
            get() = @Composable { data ->
                /* add some @Composable implementation which displays `data` */
            }
    }
}

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

sealed interface Event {
    interface Screen : Event {
        val data: Screen.Data

        interface Data {
            val value: String
        }
    }
    interface Action : Event {
        val data: Action.Data

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

analyticsCollector = { event ->
    // do whatever is needed (e.g. log the event)
    when (it) {
        is Event.Screen -> Log.i("Analytics", "Event.Screen(value = ${it.data.value})")
        is Event.Action -> Log.i("Analytics", "Event.Action(value = ${it.data.value}, screen = ${it.data.screen}, component = ${it.data.component}, label = ${it.data.label})")
    }
}

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