CausalClient

CLASS

CausalClient

public final class CausalClient: CausalClientProtocol

The main entry point to the Causal iOS SDK.

Properties

shared

public static let shared = CausalClient()

The CausalClient shared instance.

• Warning: You must set impressionServer and session before using.

debugLogging

public var debugLogging: DebugLogVerbosity

Enables or disables logs for debugging.

• See also: DebugLogVerbosity

configuration

public var configuration: URLSessionConfiguration

A configuration object that defines behavior and policies for a URL session. This can be used to supply custom request timeout intervals, additional http headers, and other request configurations.

impressionServer

public var impressionServer: URL

The URL for the impression server.

session

public var session: (any SessionProtocol)?

The current session.

Methods

init(impressionServer:session:)

public convenience init(impressionServer: URL, session: any SessionProtocol)

Construct an instance of the CausalClient for use in your application.

• Parameters:
  • impressionServer: The URL for the impression server.
  • session: The current session.

Parameters

Name	Description
impressionServer	The URL for the impression server.
session	The current session.

requestFeatures(_:impressionId:)

public func requestFeatures(_ features: [any FeatureProtocol], impressionId: ImpressionId) async -> Error?

Requests a set of features to be updated from the impression server and updates them in-place.

If your project is using SwiftUI we encourage the usage of the compiler generated view models in addition to the requestCacheFill() method to request features from the impression service. However, If you wish to use the CausalClient directly then this method is recommended.

• Note: In the event of an error the input features instance contains default values and can be used to render the feature to the screen.

• Parameters:

  • features: The features to request. Upon successful completion the features instances will be updated in-place from the impression service data.
  • impressionId: The impression id that matches the specific view of the requested features.

• Returns: A CausalError or an iOS SDK Error, if one occurred.

Parameters

Name	Description
features	The features to request. Upon successful completion the features instances will be updated in-place from the impression service data.
impressionId	The impression id that matches the specific view of the requested features.

requestFeature(_:impressionId:)

public func requestFeature(_ feature: any FeatureProtocol, impressionId: ImpressionId) async -> Error?

Requests a single feature to be updated from the impression server. The passed in feature will be updated in-place with the results from the impression service.

• Note: In the event of an error the input feature instance contains default values and can be used to render the feature to the screen.

• Parameters:

  • feature: The feature to request. Upon successful completion the feature instance will be updated in-place from the impression service data.
  • impressionId: The impression id that matches the specific view of the requested feature.

• Returns: The updated feature from the server, or the default feature if there was an error.

• Throws: A CausalError or an iOS SDK Error.

Parameters

Name	Description
feature	The feature to request. Upon successful completion the feature instance will be updated in-place from the impression service data.
impressionId	The impression id that matches the specific view of the requested feature.

requestCacheFill(features:)

public func requestCacheFill(features: [any FeatureProtocol]) async throws

Requests a set of features that will be cached for later use.

• Parameters:

  • features: The features to request.

• Throws: A CausalError or an iOS SDK Error.

Parameters

Name	Description
features	The features to request.

signal(sessionEvent:)

public func signal(sessionEvent: any SessionEvent)

Signal a session event occurred to the impression service.

An alternative to signalAndWait(sessionEvent:) that is "fire-and-forget" and ignores errors.

• Parameter sessionEvent: The session event that occurred.

Parameters

Name	Description
sessionEvent	The session event that occurred.

signalAndWait(sessionEvent:)

public func signalAndWait(sessionEvent: any SessionEvent) async throws

Signal a session event occurred to the impression service.

• Parameter sessionEvent: The session event that occurred.

Parameters

Name	Description
sessionEvent	The session event that occurred.

signal(featureEvent:)

public func signal(featureEvent: FeatureEventPayload?)

Signal a feature event occurred to the impression service.

An alternative to signalAndWait(featureEvent:) that is "fire-and-forget" and ignores errors.

• Parameter featureEvent: The feature event and the corresponding impression id of the feature at the time that the event occurred.

Parameters

Name	Description
featureEvent	The feature event and the corresponding impression id of the feature at the time that the event occurred.

signalAndWait(featureEvent:)

public func signalAndWait(featureEvent: FeatureEventPayload?) async throws

Signal a feature event occurred to the impression service.

• Parameter featureEvent: The feature event and the corresponding impression id of the feature at the time that the event occurred.

Parameters

Name	Description
featureEvent	The feature event and the corresponding impression id of the feature at the time that the event occurred.

keepAlive()

public func keepAlive()

Asynchronously instructs the server to keep the session alive. This indicates that the user is still active and the session should not expire.

clearCache()

public func clearCache()

Clears all locally cached features.

• Warning: This should rarely be used and is primarily intended for debugging.

addObserver(feature:handler:)

public func addObserver(feature: any FeatureProtocol, handler: @escaping () -> Void) throws -> ObserverToken

Add an observer for the feature. The handler callback will be triggered if a Server Sent Event (SSE) forces this feature's values to change. It is recommended to use the compiler generated FeatureViewModels as those will wire up QA observers automatically and send impression events at the correct time.

• Warning: Be sure to call the removeObserver method when your view disappears or your reference object de-initializes to prevent memory leaks.

• Parameters:

  • feature: The feature instance to monitor for SSE updates.
  • handler: Callback which will be called then the input feature is updated by a Server Sent Event

• Returns: An ObserverToken which can be used to remove the observer

Parameters

Name	Description
feature	The feature instance to monitor for SSE updates.
handler	Callback which will be called then the input feature is updated by a Server Sent Event

removeObserver(observerToken:)

public func removeObserver(observerToken: ObserverToken)

Remove the Server Sent Event (SSE) observer.

• Parameter observerToken: The ObserverToken returned when calling addObserver

Parameters

Name	Description
observerToken	The ObserverToken returned when calling addObserver