ConnectionProvider

public protocol ConnectionProvider : Sendable

The provider for connection related properties and methods.

  • The current channel configuration for currently connected CXone session.

    Declaration

    Swift

    var channelConfiguration: ChannelConfiguration { get }

  • Makes an HTTP request to get the channel configuration details.

    The most recently fetched configuration is cached in memory for five minutes, so repeated calls for the same brand, channel and environment usually resolve without a network request, and a configuration changed in the backend can take up to that long to be reflected. Only one configuration is held at a time: a call targeting a different brand, channel or environment replaces it rather than being cached alongside it. Signing out clears the cache.

    Throws

    channelConfigFailure if provided parameters do not create a valid URL.

    Throws

    sdkVersionNotSupported if the SDK version is not supported by the server.

    Throws

    DecodingError.dataCorrupted an indication that the data is corrupted or otherwise invalid.

    Throws

    DecodingError.typeMismatch if the encountered stored value is not a JSON object or otherwise cannot be converted to the required type.

    Throws

    DecodingError.keyNotFound if the response does not have an entry for the given key.

    Throws

    DecodingError.valueNotFound if a response has a null value for the given key.

    Throws

    URLError.badServerResponse if the URL Loading system received bad data from the server.

    Throws

    NSError object that indicates why the request failed

    Declaration

    Swift

    func getChannelConfiguration(environment: Environment, brandId: Int, channelId: String) async throws -> ChannelConfiguration

    Parameters

    environment

    The CXone Environment used to connect. Relates to your location.
    brandId

    The unique id of the brand for which to open the connection.
    channelId

    The unique id of the channel for the connection.

    Return Value

    Channel configuration details

  • Makes an HTTP request to get the channel configuration details.

    The most recently fetched configuration is cached in memory for five minutes, so repeated calls for the same brand, channel and chat URL usually resolve without a network request, and a configuration changed in the backend can take up to that long to be reflected. Only one configuration is held at a time: a call targeting a different brand, channel or chat URL replaces it rather than being cached alongside it. Signing out clears the cache.

    Throws

    channelConfigFailure if provided parameters do not create a valid URL.

    Throws

    sdkVersionNotSupported if the SDK version is not supported by the server.

    Throws

    DecodingError.dataCorrupted an indication that the data is corrupted or otherwise invalid.

    Throws

    DecodingError.typeMismatch if the encountered stored value is not a JSON object or otherwise cannot be converted to the required type.

    Throws

    DecodingError.keyNotFound if the response does not have an entry for the given key.

    Throws

    DecodingError.valueNotFound if a response has a null value for the given key.

    Throws

    URLError.badServerResponse if the URL Loading system received bad data from the server.

    Throws

    NSError object that indicates why the request failed

    Declaration

    Swift

    func getChannelConfiguration(chatURL: String, brandId: Int, channelId: String) async throws -> ChannelConfiguration

    Parameters

    chatURL

    The chat URL for the custom environment.
    brandId

    The unique id of the brand for which to open the connection.
    channelId

    The unique id of the channel for the connection.

    Return Value

    Channel configuration details

  • Prepares the SDK for establishing connection to the CXone service.

    In order to use any AnalyticsProvider methods, you must first call this method.

    Throws

    illegalChatState if the SDK is not in the required state to trigger the method.

    Throws

    missingParameter(_:) if connectionurl is not in correct format.

    Throws

    channelConfigFailure if the SDK could not prepare URL for URLRequest

    Throws

    DecodingError.dataCorrupted an indication that the data is corrupted or otherwise invalid.

    Throws

    DecodingError.typeMismatch if the encountered stored value is not a JSON object or otherwise cannot be converted to the required type.

    Throws

    DecodingError.keyNotFound if the response does not have an entry for the given key.

    Throws

    DecodingError.valueNotFound if a response has a null value for the given key.

    Throws

    URLError.badServerResponse if the URL Loading system received bad data from the server.

    Throws

    NSError object that indicates why the request failed

    Throws

    EncodingError.invalidValue if a non-conforming floating-point value is encountered during encoding, and the encoding strategy is .throw.

    Throws

    An error if any value throws an error during encoding.

    Declaration

    Swift

    func prepare(environment: Environment, brandId: Int, channelId: String) async throws

    Parameters

    environment

    The CXone Environment used to connect. Relates to your location.
    brandId

    The unique id of the brand for which to open the connection.
    channelId

    The unique id of the channel for the connection.

  • Prepares the SDK for establishing connection to the CXone service.

    In order to use any AnalyticsProvider methods, it is necessary to call this method before invoking any of them.

    Throws

    illegalChatState if the SDK is not in the required state to trigger the method.

    Throws

    missingParameter(_:) if connectionurl is not in correct format.

    Throws

    channelConfigFailure if the SDK could not prepare URL for URLRequest

    Throws

    DecodingError.dataCorrupted an indication that the data is corrupted or otherwise invalid.

    Throws

    DecodingError.typeMismatch if the encountered stored value is not a JSON object or otherwise cannot be converted to the required type.

    Throws

    DecodingError.keyNotFound if the response does not have an entry for the given key.

    Throws

    DecodingError.valueNotFound if a response has a null value for the given key.

    Throws

    URLError.badServerResponse if the URL Loading system received bad data from the server.

    Throws

    NSError object that indicates why the request failed

    Throws

    EncodingError.invalidValue if a non-conforming floating-point value is encountered during encoding, and the encoding strategy is .throw.

    Throws

    An error if any value throws an error during encoding.

    Declaration

    Swift

    func prepare(chatURL: String, socketURL: String, loggerURL: String, brandId: Int, channelId: String, tokenURL: String?) async throws

    Parameters

    chatURL

    The URL to be used for chat requests (channel config and attachment upload).
    socketURL

    The URL to be used for the WebSocket connection.
    loggerURL

    The URL to be use for internal chat logger.
    brandId

    The unique id of the brand for which to open the connection.
    channelId

    The unique id of the channel for the connection.
    tokenURL

    The URL to be used for transaction token requests. If nil, the URL will be automatically derived from chatURL.
  • connect() Asynchronous

    Connects to the CXone service via web socket.

    This method establishes the web socket connection. Once connected, subscribe to events() to receive ChatEvent values (thread updates, agent typing, proactive actions, errors, etc.).

    Precondition

    Either prepare(environment:brandId:channelId:) or prepare(chatURL:socketURL:loggerURL:brandId:channelId:tokenURL:) method must be called before this method.

    Throws

    illegalChatState if the SDK is not in the required state to trigger the method.

    Throws

    transactionTokenRequestFailed(statusCode:) if the transaction-token exchange fails.

    Throws

    customerAssociationFailure if the SDK could not get customer identity and it may not have been set.

    Throws

    missingAccessToken if the customer was successfully authorized, but an access token wasn’t returned.

    Throws

    invalidAccessToken if the OAuth token was rejected or is missing.

    Throws

    invalidRefreshToken(_:) if an explicit-PKCE reconnect’s refresh-grant recovery fails and no further automatic recovery is possible — the app must perform a new authorization flow.

    Throws

    invalidData when the Data object cannot be successfully converted to a valid UTF-8 string

    Throws

    invalidParameter(_:) if the socket endpoint URL has not been set properly

    Throws

    channelConfigFailure if the SDK could not prepare URL for URLRequest

    Throws

    notConnected if the pulse was not received

    Throws

    missingVisitorId if visitor ID is not set.

    Throws

    missingParameter(_:) if unable to build the URL.

    Throws

    missingParameter(_:) if unable to get cached transaction token.

    Throws

    missingParameter(_:) if setAuthorizationCode(_:) or setCodeVerifier(_:) was not called for the explicit OAuth flow.

    Throws

    EncodingError.invalidValue(_:_:) if the given value is invalid in the current context for this format.

    Throws

    URLError.badServerResponse if the URL Loading system received bad data from the server.

    Throws

    NSError object that indicates why the request failed

    Declaration

    Swift

    func connect() async throws

  • Disconnects from the CXone service and keeps the customer signed in.

    Declaration

    Swift

    func disconnect()
  • executeTrigger(_:) Asynchronous

    Manually executes a trigger that was defined in CXone. This can be used to test that proactive actions are displaying.

    Throws

    illegalChatState if the SDK is not in the required state to trigger the method.

    Throws

    notConnected if an attempt was made to use a method without connecting first. Make sure you call the connect method first.

    Throws

    customerVisitorAssociationFailure if the customer could not be associated with a visitor.

    Throws

    customerAssociationFailure The SDK instance could not get customer identity possibly because it may not have been set.

    Throws

    invalidData when the Data object cannot be successfully converted to a valid UTF-8 string

    Throws

    EncodingError.invalidValue(_:_:) if the given value is invalid in the current context for this format.

    Throws

    An error if any value throws an error during encoding.

    Declaration

    Swift

    func executeTrigger(_ triggerId: String) async throws

    Parameters

    triggerId

    The id of the trigger to manually execute.