UnbluCoreApi

@objc
class UnbluCoreApi

The API to use to access unblu suite functionality like showing, opening conversations

Before calling any other function #configureApi should be called inside the AppDelegate.

Use the constants of UnbluEventApi to register for events and access their user info data

A typical flow for the usage would be:

AppDelegate#application() {
   UnbluCoreApi.instance.configureApi(UnbluClientConfiguration(unbluBaseUrl: "<base-url>", apiKey: "<apiKey>"))

   //register for general errors and/or also other events
   NotificationCenter.default.addObserver(self, selector: #selector(AppDelegate.handleErrorEvent(notification:)), name: Notification.Name.UnbluError, object: nil)

   //start the api. This could also be done later when it is needed, but it will take a while until the api is ready
   UnbluCoreApi.instance.initApi(success: {<success handling>}, failure: {<error handling>})
}

SomeViewController#showConversations() {
   //the conversations should be shown
   UnbluCoreApi.instance.showUi(visible: true)
}

  • This can be used to separate a custom Unblu presentation UIWindow from others.

    Declaration

    Swift

    static let presentationIndicatorWindowTag: Int

  • Defines the log level of the Unblu SDK. All messages with a lower level will not be logged.

    Default value is LogLevel.info

    Declaration

    Swift

    static var logLevel: LogLevel

  • The name for the icon image that will be displayed on an active conversation indicator button. The icon with this name must be included in the app’s resources, and it is recommended that the minimum size of the icon is 80x80 pixels and It is preferable to have a round icon. If this name is not set, the avatar of the current agent will be displayed instead.

    Declaration

    Swift

    var activeConversationIndicatorIconName: String? { get set }

  • Indicates whether indicators have a removal area or not.

    Declaration

    Swift

    var indicatorsHaveRemovalArea: Bool { get set }

  • The delegate for Unblu related events

    Declaration

    Swift

    weak var visitorDelegate: (any UnbluVisitorClientDelegate)? { get set }

  • The delegate for Unblu related events

    Declaration

    Swift

    weak var agentDelegate: (any UnbluAgentClientDelegate)? { get set }

  • Set the OAuth 2.0 token to pass to service worker and used in the authorization header. Bearer Token Usage: https://datatracker.ietf.org/doc/html/rfc6750 This also sets the WebSocket authorization token via the Sec-WebSocket-Protocol header.

    Declaration

    Swift

    func setOAuthToken(token: String)

    Parameters

    token

    The token received from an identity provider

  • Set to enable if the floating button should appear when a conversation is open and the UnbluView is gets hidden It is disabled per default.

    Declaration

    Swift

    func setEnabledFloatingActiveConversationIndicator(_ enabled: Bool)

    Parameters

    enabled

    true to display the floating button, otherwise false

  • Check if floating active conversation indicator can be displayed and show it if it’s not visible.

    Declaration

    Swift

    func showFloatingActiveConversationIndicator()

  • Shows an existing Unblu view in a new modal window. This temporarily moves the view from the current hierarchy to a new global window. After closing the new window, the Unblu view will be moved back to its previous location. This function can also be used if the Unblu view is not added anywhere. This function should not be used if the unblu view is visible. In this case first remove the Unblu view from its current parent. NOTE: Ensure that if the Unblu view is displayed modally with this function to also call dismissModalView before attching the unblu view directly somewhere else.

    Declaration

    Swift

    func presentingAsModalView(reason: UnbluUiRequestReason, with animation: UnbluPresentationAnimationStyle, shadowStyle: UnbluPresentationShadowStyle, _ anchor: CGRect? = nil)

    Parameters

    reason

    The reason why the view is displayed modally. Typically this is either ‘UnbluUiRequestReason.floatingActiveConversationButtonPressed’ or ‘UnbluUiRequestReason.pipButtonRequest’
    shadowStyle

    The style of shadow that the window has
    anchor

    This is optional. The frame to/from of which the window expands/collapses.

  • Checks if the Unblu view is presented as a modal view and is visible or not. * NOTE: If it is visible when receiving didRequestHideUi, ‘dismissModalView’ should be used to hide the modal view.

    Declaration

    Swift

    func isModalViewVisible() -> Bool

  • Hide the current modal window with the animation effect used to open NOTE: this should only be called after calling presentingAsModalView and before trying to attach the Unblu view somewhere else directly if needed because it puts Unblu in its old place in the window hierarchy

    Declaration

    Swift

    func dismissModalView()

  • Set Unblu view mode to modal view mode, this means removing the navigation pointer (back to overview, etc.)

    Declaration

    Swift

    func setModalMode(enabled: Bool, _ completion: @escaping (Bool) -> Void)

    Parameters

    enabled

    true to remove the navigation pointer, otherwise false

  • The UnbluConversationInterceptor for intercepting conversation-related events from Unblu.

    Declaration

    Swift

    var conversationInterceptor: (any UnbluConversationInterceptor)? { get set }
    • Starts a new Conversation and places it into the inbound conversation queue. *
    • Starting a new conversation involves an agent availability check.
    • For [[ConversationType.offlineChatRequest]] conversations, the check proceeds as follows:
    • * If an agent is available, the conversation type is changed to [[ConversationType.chatRequest]].
    • * If no agents are available, it starts an offline conversation provided offline chat requests are enabled in the Unblu server’s configuration.
    • * if offline chat requests are disabled, the request is rejected. *
    • For all online conversation types, the check works as follows:
    • * If an agent is available, the conversation is started.
    • * If no agents are available, the request is rejected. *
    • You should therefore always check agent availability before starting a new conversation.
    • If no agents are available, only start conversations of the type [[ConversationType.offlineChatRequest]].

    Declaration

    Swift

    func startNewConversation(conversationType: ConversationType, customVisitorData: String?, conversationRecipient: ConversationRecipient?, onComplete: @escaping (Result<any UnbluConversation, UnbluInitConversationError>) -> Void)

  • Joins an Unblu mobile co-browsing session started by an agent. This is an asynchronous call. Use the callback to check for success or failure.

    Declaration

    Swift

    @available(*, deprecated, message: "Use joinConversation with Result<UnbluConversation, UnbluJoinConversationError> instead")
func joinConversation(pin: String, onComplete: @escaping (Result<any UnbluConversation, UnbluInitConversationError>) -> Void)

    Parameters

    pin

    The pin for the conversation to join. The pin is provided by the Agent Desk.
    onComplete

    A Result containing the UnbluConversation of the conversation with the mobile co-browsing session that the visitor joined, or an UnbluApiInitConversationError if joining the mobile co-browsing session failed.

  • Joins an Unblu mobile co-browsing session started by an agent. This is an asynchronous call. Use the callback to check for success or failure.

    Declaration

    Swift

    func joinConversation(pin: String, completion onComplete: @escaping (Result<any UnbluConversation, UnbluJoinConversationError>) -> Void)

    Parameters

    pin

    The pin for the conversation to join. The pin is provided by the Agent Desk.

  • Checks if at least one agent is available for mobile co-browsing or chat.

    This is an asynchronous call. Use the callbacks to check for success or failure.

    Declaration

    Swift

    func isAgentAvailable(onComplete: @escaping (Result<Bool, UnbluClientNotInitializedError>) -> Void)

    Parameters

    onComplete

    A Result reporting success with true or false to indicate whether an agent is available, or an UnbluApiNotInitializedError if checking agent availability failed.

  • Activates the real visitor session. if Unblu view is not yet visible after calling this method, all API requests will work. If the visitor session is already active, this will do nothing.

    Declaration

    Swift

    func activateVisitorSession(completion: @escaping () -> Void)

  • Adds a label to the current person.

    This method is only compatible with version 8.0.0 or newer of the Collaboration Server.

    Declaration

    Swift

    func addPersonLabel(name: String, onComplete: @escaping (Bool) -> Void)

    Parameters

    name

    The name of the label to add

  • Removes a label from the current person.

    This method is only compatible with version 8.0.0 or newer of the Collaboration Server.

    Declaration

    Swift

    func removePersonLabel(name: String, onComplete: @escaping (Bool) -> Void)

    Parameters

    name

    The name of the label to remove.

  • Sets visitor data for the active conversation.

    Declaration

    Swift

    func setVisitorData(data: String, onComplete: @escaping (Bool) -> Void)

    Parameters

    data

    The visitor data to be set.
    onComplete

    A closure called upon completion. The closure receives a Bool indicating whether the operation was successful.

  • Sets visitor data for the active conversation with detailed error information.

    Declaration

    Swift

    func setVisitorDataWithError(data: String, onComplete: @escaping (Bool, String?) -> Void)

    Parameters

    data

    The visitor data to be set.
    onComplete

    A closure called upon completion of the operation. The closure receives: -result: A Bool indicating whether the operation was successful (true) or not (false). -errorDescription: An optional String providing details in case of failure.

  • Retrieves visitor data for the active conversation.

    Declaration

    Swift

    func getVisitorData(onComplete: @escaping (String?) -> Void)

    Parameters

    onComplete

    A closure that is called with the visitor data result. Passes a non-nil result if successful and the value is defined, otherwise nil.

  • The view into which Unblu content will be rendered.

    Declaration

    Swift

    var view: any UnbluView { get }

  • The current displayed UnbluConversation, or nil if there is no conversation currently displayed.

    Declaration

    Swift

    var openConversation: (any UnbluConversation)? { get }

  • The current unread messages count

    Declaration

    Swift

    var unreadMessagesCount: Int { get }

  • The user agent postfix used inside the WKWebView of the Unblu SDK. This is important for the Collaboration Server to identify the WKWebView and facilitate proper communication between the JavaScript and native code. The value is assigned to WKWebViewConfiguration.applicationNameForUserAgent. For more information, refer to https://developer.apple.com/documentation/webkit/wkwebviewconfiguration/1395665-applicationnameforuseragent.

    Declaration

    Swift

    var userAgentPostFix: String { get }

  • Enables the debug output of the Unblu SDK. This contains additional information on log messages and is independent of the log level defined with logLevel.

    Declaration

    Swift

    var enableDebugOutput: Bool { get set }

  • Defines the log level of the Unblu SDK. Messages with a lower level will not be logged.

    The default value is LogLevel.info.

    Declaration

    Swift

    var logLevel: LogLevel { get set }

  • Stops the UI from scrolling when the keyboard is shown or hidden.

    This setting should only be changed if it causes issues. If it is disabled, the user of the SDK has to ensure that the UI container/the webview inside is resized correctly when necessary.

    Declaration

    Swift

    var preventScrollingByKeyboard: Bool { get set }

  • Custom loading view creator used whenever a loading view is displayed.

    Declaration

    Swift

    var customLoadingViewCreator: (any UnbluCustomLoadingViewCreator)? { get set }

  • Sets or updates the named area. This can be done independently of the state of the client, but it has a different effect depending on the current client state.

    • If the client has not been started when you set the named area, the configuration of the named area is loaded as soon as the client is started.
    • If you set the named area and the client has already been started, it can only be used on the Agent Desk to filter incoming requests in the queue. No specific configuration will be loaded for the named area.
    • If a conversation is already open, setting the named area has no effect until one of two events occur:
      • The UnbluClient is started again, which loads the configuration of the named area.
      • A new conversation is started, which results in the queue being filtered by the newly set named area

    Declaration

    Swift

    var namedArea: String? { get set }

  • Sets or updates custom cookies. When set, the UnbluCookie objects are passed to the Unblu WebView, which then uses them in future network requests. This can be done independently of the client’s current state. If the client has already been started, setting customCookies overwrites any existing cookies with the same key in the WebView. The other cookies are not affected. Cookies set here will be used by the WebView whether it’s waiting to be started or already running.

    Declaration

    Swift

    var customCookies: Set<UnbluCookie> { get set }

  • Initializes the Unblu client.

    Connects to the unblu server and makes the API ready for further calls.

    This is an asynchronous call. Any further calls can be made in the success callback or after receiving the ApiIsInitialized notification.

    Subsequent calls without deinitialization beforehand will be ignored. The callbacks, however, will be triggered as soon as there is a Result.

    Declaration

    Swift

    func start(_ completion: @escaping (Result<Void, UnbluClientInitializeError>) -> Void)

    Parameters

    completion

    The callback that will be called with a Result type once the client has been initialized successfully, or with an UnbluApiInitializeError if initialization failed.

  • Initializes the Unblu client.

    Connects to the unblu server and makes the API ready for further calls then tries to open a conversation with the passed id

    This is an asynchronous call. Any further calls can be made in the success callback or after receiving the ApiIsInitialized notification.

    Subsequent calls without deinitialization beforehand will be ignored. The callbacks, however, will be triggered as soon as there is a Result.

    Declaration

    Swift

    func start(with conversationId: String, _ completion: @escaping (Result<Void, UnbluClientInitializeError>, Result<any UnbluConversation, UnbluOpenConversationError>) -> Void)

    Parameters

    completion

    The callback that will be called with a Result type once the client has been initialized successfully, or with an UnbluApiInitializeError if initialization failed. The Second result containing the UnbluConversation that was opened, or an UnbluApiOpenConversationError if opening failed.

  • Deinitializes the Unblu client.

    Calling this method will free all resources allocated to the Unblu client.

    This is an asynchronous call. Use the callback to check for success or failure.

    Consecutive calls (without initializing inbetween) will be ignored, but the callback will also be triggered, as soon as there is a result.

    Note

    This function invokes a full deinitialization, which is responsible for cleaning up the application state and freeing up resources. It also disconnects from the Collaboration Server properly. As a result, the function may take up to five seconds to complete, depending on the user’s network connection.

    Declaration

    Swift

    func stop(_ completion: ((Result<Void, UnbluDeinitializeError>) -> Void)?)

    Parameters

    completion

    completion: The (optional) callback that will be called with a Result type once the Unblu client has been deinitialized successfully, or with an UnbluApiDeinitializeError if deinitialization failed.

  • Returns true if the Unblu client was initialized and the initialization was successful, and false if the Unblu client is not initialized or is in an error state.

    This is an asynchronous call. Use the callbacks to check for success or failure.

    Declaration

    Swift

    func isInitialized(success: @escaping (Bool) -> Void)

    Parameters

    success

    The callback called with true if the Unblu client is initialized and with false otherwise.

  • Returns true if the client is in error state, and false otherwise.

    This is an asynchronous call. Use the callbacks to check for success or failure.

    Declaration

    Swift

    func isInErrorState(success: @escaping (Bool) -> Void)

    Parameters

    success

    The callback called with true if the Unblu client is in an error state and with false otherwise.

  • Opens and displays a conversation with the given ID in the UnbluView.

    Declaration

    Swift

    func openConversation(_ conversationId: String, onComplete: @escaping (Result<any UnbluConversation, UnbluOpenConversationError>) -> Void)

    Parameters

    conversationId

    The ID of the conversation to open.
    onComplete

    A Result containing the UnbluConversation that was opened, or an UnbluApiOpenConversationError if opening failed.

  • Opens the conversation overview.

    Declaration

    Swift

    func openConversationOverview(onComplete: @escaping (Result<Void, UnbluOpenConversationOverviewError>) -> Void)

    Parameters

    onComplete

    A Result representing success if the conversation overview was opened, or an UnbluApiOpenConversationOverviewError if opening the overview failed.

  • Returns the information on the person currently interacting with the Unblu client.

    Declaration

    Swift

    func getPersonInfo(onComplete: @escaping (Result<PersonInfo, UnbluRetrievePersonInfoError>) -> Void)

    Parameters

    onComplete

    A Result containing the current PersonInfo of the person currently identified, or an UnbluApiRetrievePersonInfoError if retrieving the person’s information failed.

  • Returns all accessible conversations of the current user. If no conversation is present, an empty array is returned.

    Declaration

    Swift

    func getConversations(completion: @escaping ([ConversationInfo]) -> Void)

  • Helper to quickly check if is initialized. Should only be called inside an main.async queue

    Declaration

    Swift

    func isInitializedInternal() -> Bool