Using the iOS Renderer
iOS Project Requirements
The minimum requirements are:- iOS 15
- Swift 5.7
Installing the library
The iOS Renderer is available through Cocoapods.Cocoapods
Prerequisites
- Cocoapods gem installed
Cocoapods private trunk setup
Add the private trunk repo to your local Cocoapods installation with the command:Adding the dependency
Add the source of the private repository in the PodfileBUILD_LIBRARY_FOR_DISTRIBUTION
to YES
.
pod install
Library dependencies
- Alamofire
- SDWebImageSwiftUI
- SDWebImageSVGCoder
Configuring the library
The SDK has 2 configurations, available through shared instances:FXConfig
which holds general purpose properties, and FXSessionConfig
which holds user session properties.
It is recommended to call the FXConfig
configuration method at app launch.
Call the FXSessionConfig configure method after the user logs in and a valid user session is available.
FXConfig
This config is used for general purpose properties.Properties
Name | Description | Type | Requirement |
---|---|---|---|
baseURL | The base URL used for REST networking | String | Mandatory |
enginePath | The process engine url path component | String | Mandatory |
imageBaseURL | The base URL used for static assets | String | Mandatory |
locale | The locale used for localization | String | Mandatory. Defaults to “en-us” |
language | The language used for retrieving enumerations and substitution tags | String | Mandatory. Defaults to “en” |
logLevel | Enum value indicating the log level logging. Default is none | Bool | Optional |
Changing the current language
The current language and locale can be changed after the initial configuration, by calling thechangeLocaleSettings
method:
FXSessionConfig
This config is used for providing networking or auth session-specific properties. The library expects either the JWT access token or an Alamofire Session instance managed by the container app. In case a session object is provided, the request adapting should be handled by the container app.Properties
Name | Description | Type |
---|---|---|
sessionManager | Alamofire session instance used for REST networking | Session |
token | JWT authentication access token | String |
Sample for access token
Sample for session
Theming
Make sure the
FXSessionConfig
configure method was called with a valid session before setting up the theme.Theme setup
The setup theme is called using the shared instance ofFXTheme
-
uuid
- the UUID of the theme configured in the FlowX Designer. -
localFileUrl
- optional parameter for providing a fallback theme file, in case the fetch theme request fails. -
completion
- a completion closure called when the theme setup finishes.
completion
parameter, FXTheme’s shared instance also provides a Combine publisher named themeFetched
which sends true
if the theme setup was finished.
Sample
Using the library
Public API
The library’s public APIs described in this section are called using the shared instance of FlowX,FlowX.sharedInstance
.
Check renderer compatibility
Before using the iOS SDK, it is recommended to check the compatibility between the renderer and the deployed FlowX services. This can be done by calling thecheckRendererVersion
which has a completion handler containing a Bool value.
How to start and end FlowX session
After all the configurations are set, you can start a FlowX session by calling thestartSession()
method.
This is optional, as the session starts lazily when the first process is started.
FlowX.sharedInstance.startSession()
When you want to end a FlowX session, you can call the endSession()
method. This also does a complete clean-up of the started processes.
You might want to use this method in a variety of scenarios, for instance when the user logs out.
FlowX.sharedInstance.endSession()
How to start a process
There are 3 methods available for starting a FlowX process. The container app is responsible with presenting the navigation controller or tab controller holding the process navigation.- Start a process which renders inside an instance of
UINavigationController
orUITabBarController
, depending on the BPMN diagram of the process.
completion
closure parameter of the method.
Use this method when you want the process to be rendered inside a controller themed using the FlowX Theme defined in the FlowX Designer.
-
projectId
- the uuid of the project -
name
- the name of the process -
params
- the start parameters, if any -
isModal
- a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation. -
showLoader
- a boolean indicating whether the loader should be displayed when starting the process. -
completion
- a completion closure which passes either an instance ofUINavigationController
orUITabBarController
to be presented. -
onProcessEnded
- a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using [weak self]
- Start a process which renders inside a provided instance of a
UINavigationController
.
Use this method when you want the process to be rendered inside a custom instance of
Optionally you can pass an instance of
UINavigationController
.Optionally you can pass an instance of
FXNavigationViewController
, which has the appearance set in the FlowX Theme, using the FXNavigationViewController
s class func FXNavigationViewController.navigationController()
.-
navigationController
- the instance of UINavigationController which will hold the process navigation stack -
projectId
- the uuid of the project -
name
- the name of the process -
params
- the start parameters, if any -
isModal
- a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation. -
showLoader
- a boolean indicating whether the loader should be displayed when starting the process. -
onProcessEnded
- a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using [weak self]
- Start a process which renders inside a provided instance of a
UITabBarController
.
Use this method when you want the process to be rendered inside a custom instance of
UITabBarController
.If you use this method, make sure that the process has a tab controller as root view.
-
tabBarController
- the instance of UITabBarController which will hold the process navigation -
projectId
- the uuid of the project -
name
- the name of the process -
params
- the start parameters, if any -
isModal
- a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation. -
showLoader
- a boolean indicating whether the loader should be displayed when starting the process. -
onProcessEnded
- a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using [weak self]
Sample
How to resume an existing process
There are 3 methods available for resuming a FlowX process. The container app is responsible with presenting the navigation controller or tab controller holding the process navigation.- Continue a process which renders inside an instance of
UINavigationController
orUITabBarController
, depending on the BPMN diagram of the process.
completion
closure parameter of the method.
Use this method when you want the process to be rendered inside a controller themed using the FlowX Theme defined in the FlowX Designer.
-
name
- the name of the process -
isModal
- a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation. -
showLoader
- a boolean indicating whether the loader should be displayed when starting the process. -
completion
- a completion closure which passes either an instance ofUINavigationController
orUITabBarController
to be presented. -
onProcessEnded
- a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using [weak self]
- Continue a process which renders inside a provided instance of a
UINavigationController
.
Use this method when you want the process to be rendered inside a custom instance of
Optionally you can pass an instance of
UINavigationController
.Optionally you can pass an instance of
FXNavigationViewController
, which has the appearance set in the FlowX Theme, using the FXNavigationViewController
s class func FXNavigationViewController.navigationController()
.-
uuid
- the UUID string of the process -
name
- the name of the process -
navigationController
- the instance of UINavigationController which will hold the process navigation stack -
isModal
- a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation. -
onProcessEnded
- a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using [weak self]
- Continue a process which renders inside a provided instance of a
UITabBarController
.
Use this method when you want the process to be rendered inside a custom instance of
UITabBarController
.If you use this method, make sure that the process has a tab controller as root view.
-
uuid
- the UUID string of the process -
name
- the name of the process -
tabBarController
- the instance of UITabBarController which will hold the process navigation -
isModal
- a boolean indicating whether the process navigation is modally displayed. When the process navigation is displayed modally, a close bar button item is displayed on each screen displayed throughout the process navigation. -
onProcessEnded
- a closure called when the process ends. The closure is strongly referenced inside the SDK. Avoid reference cycles by using [weak self]
Sample
How to end a process
You can manually end a process by calling thestopProcess(name: String)
method.
This is useful when you want to explicitly ask the FlowX shared instance to clean up the instance of the process sent as parameter.
For example, it could be used for modally displayed processes that are dismissed by the user, in which case the dismissRequested(forProcess process: String, navigationController: UINavigationController)
method of the FXDataSource will be called.
Sample
FXDataSource
The library offers a way of communication with the container app through theFXDataSource
protocol.
The data source is a public property of FlowX shared instance.
public weak var dataSource: FXDataSource?
func controllerFor(componentIdentifier: String) -> FXController?
func viewFor(componentIdentifier: String) -> FXView?
func viewFor(componentIdentifier: String, customComponentViewModel: FXCustomComponentViewModel) -> AnyView?
func navigationController() -> UINavigationController?
UINavigationController
class, or just a regular UINavigationController
instance themed by the container app.
func errorReceivedForAction(name: String?)
func validate(validatorName: String, value: String) -> Bool
func dismissRequested(forProcess process: String, navigationController: UINavigationController)
func viewForStepperHeader(stepViewModel: StepViewModel) -> AnyView?
func track(event: TrackEvent)
TrackEvent
enum, which can represent a screen or an action.
func newProcessStarted(processInstanceUuid: String)
START_PROJECT
action. The parameter is the uuid of the process instance. The container app is responsible for dismissing the navigation of the current process and displaying the new process navigation.
Sample
Custom components
FXController
FXController is an open class subclassing UIViewController, which helps the container app provide full custom screens the renderer. It needs to be subclassed for each custom screen.Use this only when the custom component configured in the UI Designer is the root component of the User Task node.
internal(set) public var data: Any?
data
is the property, containing the data model for the custom component. The type is Any, as it could be a primitive value, a dictionary or an array, depending on the component configuration.
internal(set) public var actions: [ProcessActionModel]?
actions
is the array of actions provided to the custom component.
func titleForScreen() -> String?
func populateUI()
func updateUI()
FXView
FXView is a protocol that helps the container app provide custom UIKit subviews to the renderer. It needs to be implemented byUIView
instances. Similar to FXController
it has data and actions properties and a populate method.
var data: [String: Any]?
data
is the property, containing the data model for the custom view. The type is Any, as it could be a primitive value, a dictionary or an array, depending on the component configuration.
var actions: [ProcessActionModel]?
actions
is the array of actions provided to the custom view.
func populateUI()
It is mandatory for views implementing the FXView protocol to provide the intrinsic content size.
SwiftUI Custom components
Custom SwiftUI components can be provided as type-erased views.FXCustomComponentViewModel
is a class implementing the ObservableObject
protocol. It is used for managing the state of custom SwiftUI views.
It has two published properties, for data and actions. It also includes a saveData
dictionary and a validate
closure used for submitting and validating data from the custom components.
Validating SwiftUI Custom Components
A SwiftUI Custom Component can validate and submit data from a custom component, when executing an action from a FlowX.AI UI Component.-
public var saveData: [String: Any]?
Used for setting data to be submitted from the custom component. -
public var validate: (() -> Bool)?
Used for validating the custom component data before executing the action.
Sample
Custom header view for Stepper navigation
The container application can provide a custom view that will be used as the stepper navigation header, using theFXDataSource
protocol method viewForStepperHeader
.
The method has a parameter, which provides the data needed for populating the view’s UI.
Sample
How to run an action from a custom component
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 following method:action
- the ProcessActionModel
action object
params
- the parameters for the action
How to run an upload action from a custom component
action
- the ProcessActionModel
action object
image
- the image to upload
action
- the ProcessActionModel
action object
fileURL
- the local URL of the image
Getting a substitution tag value by key
Getting a media item url by key
Handling authorization token changes
When the access token of the auth session changes, you can update it in the renderer using thefunc updateAuthorization(token: String)
method.