The WebexConnect Core SDK serves as the primary interface for managing the lifecycle of the SDK, encompassing a wide range of functionalities. It allows for starting and shutting down the SDK, thereby managing its initialization and teardown. Additionally, it handles device profile management by providing capabilities to register, unregister, retrieve, and update device profiles. It also supports user registration checks to determine if the SDK is started or if a user is registered. It includes features for updating and removing device profile parameters, publishing custom events to the platform, and managing various configuration options within the SDK. Furthermore, it ensures security by setting security tokens and supports logging by configuring custom loggers, making it a comprehensive tool for SDK lifecycle management.

Core SDK Classes/Protocols/Enums

Below is the table with the Core SDK Classes/Protocols/Enums and their descriptions:

WebexConnect

Below is the table with the WebexConnect methods and their descriptions

Config

Below is the table with the Config methods and their descriptions

DeviceProfile

Below is the table with the DeviceProfile methods and their descriptions

Logger

Below is the table with the Logger methods and their descriptions

Console Logger

Below is the table with the Console Logger methods and their descriptions

File Logger

Below is the table with the File Logger methods and their descriptions

Environment

Below is the table with the Environment methods and their descriptions

SecurityTokenErrorDelegate

WebexConnect

This class contains the methods to initialize the SDK and register a user. When integrating the SDK into your app, it is mandatory to use this class to initialize the SDK.

Methods

startup((completionHandler:)

This method initializes the SDK, reading configuration from the configuration file (IMIconnectConfig.plist/ WebexConnectConfig.plist).

Syntax: func startup(completionHandler: @escaping (Error?) -> Void)

Parameters

Sample Code

// Get the shared instance of WebexConnect
let webexConnect = WebexConnectProvider.instance
// Start the SDK using the default configuration
webexConnect.startup { error in
    if let error = error {
        print("Startup failed: \(error.localizedDescription)")
    } else {
        print("SDK started successfully")
    }
}

// Get the shared instance of WebexConnect
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
// Start the SDK using the default configuration
[webexConnect startupWithCompletionHandler:^(NSError *error) {
    if (error) {
        NSLog(@"Startup failed: %@", error.localizedDescription);
    } else {
        NSLog(@"SDK started successfully");
    }
}];

startup(config:completionHandler)

This method initializes the SDK using the passed configuration.

Syntax func startup(config: Config, completionHandler: @escaping (Error?) -> Void)

Parameters

Sample Code

// Get the shared instance of WebexConnect
let webexConnect = WebexConnectProvider.instance
// Create a config object with your app details
let config = Config(appId: "yourAppId", clientKey: "yourClientKey", environment: .uk)
// Start the SDK with the custom config
webexConnect.startup(config: config) { error in
    if let error = error {
        print("Startup failed: \(error.localizedDescription)")
    } else {
        print("SDK started successfully with custom config")
    }
}

// Get the shared instance of WebexConnect
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
// Create a config object with your app details
Config *config = [[Config alloc] initWithAppId:@"yourAppId" clientKey:@"yourClientKey" serverDomain:@"custom-server-domain" environment:Environment.uk groupIdentifier:@"group.com.example.app"];
// Start the SDK with the custom config
[webexConnect startupWithConfig:config completionHandler:^(NSError *error) {
    if (error) {
        NSLog(@"Startup failed: %@", error.localizedDescription);
    } else {
        NSLog(@"SDK started successfully with custom config");
    }
}];

startup(with: launchOptions: connectionOptions: completionHandler:)

This method initializes the SDK using the passed configuration options. An error can be passed in parameters, which will be set if something goes wrong during the startup process. This method is mandatory if (IMIconnectConfig.plist/WebexConnectConfig.plist) is not used.

Syntax: func startup(config: Config?, launchOptions: [UIApplication.LaunchOptionsKey: Any]?, connectionOptions: UIScene.ConnectionOptions?, completionHandler: @escaping (Error?) -> Void)

Parameters

Sample Code:

// Get the shared instance of WebexConnect
let webexConnect = WebexConnectProvider.instance
// Optionally create a config object or pass nil to use the default
let config: Config? = nil
// Use launchOptions and connectionOptions from your AppDelegate/SceneDelegate
let launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
let connectionOptions: UIScene.ConnectionOptions? = nil
// Start the SDK
webexConnect.startup(config: config, launchOptions: launchOptions, connectionOptions: connectionOptions) { error in
    if let error = error {
        print("Startup failed: \(error.localizedDescription)")
    } else {
        print("SDK started successfully with options")
    }
}

// Get the shared instance of WebexConnect
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
// Optionally create a config object or pass nil to use the default
Config *config = nil;
// Use launchOptions and connectionOptions from your AppDelegate/SceneDelegate
NSDictionary *launchOptions = nil;
UISceneConnectionOptions *connectionOptions = nil;
// Start the SDK
[webexConnect startupWithConfig:config launchOptions:launchOptions connectionOptions:connectionOptions completionHandler:^(NSError *error) {
    if (error) {
        NSLog(@"Startup failed: %@", error.localizedDescription);
    } else {
        NSLog(@"SDK started successfully with options");
    }
}];

shutdown(completionHandler:)

This method is used to clean up the SDK, freeing all internal object instances. Invoking this method will stop the SDK features from functioning as such Real-Time Messages and Push notifications.

Syntax func shutdown(completionHandler: @escaping (Error?) -> Void)

📘

Note

Usage of this method is not required unless there are a few limited cases where you may wish to use it; for example, if you are only using the Authentication or Monitoring features.

Parameters

Sample Code:

// Get the shared instance of WebexConnect
let webexConnect = WebexConnectProvider.instance
// Shutdown the SDK
webexConnect.shutdown { error in
    if let error = error {
        print("Shutdown failed: \(error.localizedDescription)")
    } else {
        print("SDK shutdown successfully")
    }
}

// Get the shared instance of WebexConnect
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
// Shutdown the SDK
[webexConnect shutdown:^(NSError *error) {
    if (error) {
        NSLog(@"Shutdown failed: %@", error.localizedDescription);
    } else {
        NSLog(@"SDK shutdown successfully");
    }
}];

isStarted

This method is used to check if the SDK is started.

Syntax var isStarted: Bool { get }

Return Value: True if the client is started, False otherwise

Sample Code

// Get the shared instance of WebexConnect
let webexConnect = WebexConnectProvider.instance
// Check if the SDK is started
if webexConnect.isStarted {
    print("SDK is started")
} else {
    print("SDK is not started")
}

// Get the shared instance of WebexConnect
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
// Check if the SDK is started
if (webexConnect.isStarted) {
    NSLog(@"SDK is started");
} else {
    NSLog(@"SDK is not started");
}

register(deviceProfile:completionHandler)

This method registers the device profile with the SDK, and sends the profile details to Webex Connect platform. Once a profile is registered, all further SDK calls take place in the context of that profile.

Syntax: func register(deviceProfile: DeviceProfile, completionHandler:@escaping ([String: Any]?, Error?) -> Void)

Parameters

Sample Code:

// Get the shared instance of WebexConnect
let webexConnect = WebexConnectProvider.instance
// Create a DeviceProfile object with your details
let deviceProfile = DeviceProfile(deviceId: "device-id", userId: "user123")
// Register the device profile
webexConnect.register(deviceProfile: deviceProfile) { result, error in
    if let error {
        print("Registration failed: \(error.localizedDescription)")
    } else if let result {
        print("Registration result: \(result)")
    }
}

// Get the shared instance of WebexConnect
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
// Create a DeviceProfile object with your details
DeviceProfile *deviceProfile = [[DeviceProfile alloc] initWithDeviceId:@"device-id" userId:@"userId" isGuest:false];
// Register the device profile
[webexConnect registerWithDeviceProfile:deviceProfile completionHandler:^(NSDictionary *result, NSError *error) {
    if (error) {
        NSLog(@"Registration failed: %@", error.localizedDescription);
    } else {
        NSLog(@"Registration result: %@", result);
    }
}];

deviceProfile

This method retrieves the currently registered device profile.

Syntax var deviceProfile: DeviceProfile? { get }

Return Value: The current registered device profile.

Sample Code:

// Get the shared instance of WebexConnect
let webexConnect = WebexConnectProvider.instance
// Access the current device profile
if let profile = webexConnect.deviceProfile {
    print("Device profile: \(profile)")
} else {
    print("No device profile registered")
} 

// Get the shared instance of WebexConnect
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
// Access the current device profile
DeviceProfile *profile = webexConnect.deviceProfile;
if (profile) {
    NSLog(@"Device profile: %@", profile);
} else {
    NSLog(@"No device profile registered");
}

isRegistered

This method is used to check whether the user is currently registered with Webex Connect. This method returns true if the user is registered, else false is returned.

Syntax: var isRegistered: Bool { get }

Return Value: True if the user is currently registered.

Sample Code:

// Get the shared instance of WebexConnect
let webexConnect = WebexConnectProvider.instance
// Check if the user is registered
if webexConnect.isRegistered {
    print("User is registered")
} else {
    print("User is not registered")
}

// Get the shared instance of WebexConnect
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
// Check if the user is registered
if (webexConnect.isRegistered) {
    NSLog(@"User is registered");
} else {
    NSLog(@"User is not registered");
}

📘

Note

The SDK automatically unregisters the app user if the app isn't opened for over 40 days. To ensure a seamless user experience, always check if the user is registered by calling isRegistered whenever the app launches, and if not registered, register the user with register. For further details of the profile clean up process, including how profiles are deemed inactive, please see this article.

unregister(completionHandler:)

This method unregisters the current device profile.

Syntax func unregister(completionHandler: @escaping ([String: Any]?, Error?) -> Void)

Parameters

📘

Note

Features that rely on a registered user will no longer function after this has been called.

Sample Code:

// Get the shared instance of WebexConnect
let webexConnect = WebexConnectProvider.instance
// Unregister the device profile
webexConnect.unregister { result, error in
    if let error = error {
        print("Unregister failed: \(error.localizedDescription)")
    } else {
        print("Unregister successful: \(String(describing: result))")
    }
}

// Get the shared instance of WebexConnect
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
// Unregister the device profile
[webexConnect unregisterWithCompletionHandler:^(NSDictionary *result, NSError *error) {
    if (error) {
        NSLog(@"Unregister failed: %@", error.localizedDescription);
    } else {
        NSLog(@"Unregister successful: %@", result);
    }
}];

sdkVersion

This method retrieves the SDK version number.

Syntax: var sdkVersion: String { get }

Return Value: A string representing the version number of the SDK.

Sample Code:

// Get the shared instance of WebexConnect
let webexConnect = WebexConnectProvider.instance
// Print the SDK version
print("SDK Version: \(webexConnect.sdkVersion)")

// Get the shared instance of WebexConnect
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
// Print the SDK version
NSLog(@"SDK Version: %@", webexConnect.sdkVersion);

setSecurityToken(:)

This method is used to set security token to provide better access control for user-centric resources. This method allows developers to specify the Security Token that the SDK will pass to the Gateway API calls.

Syntax: func setSecurityToken(_ token: String)

Parameters

Sample Code:

// Get the shared instance of WebexConnect
let webexConnect = WebexConnectProvider.instance
// Set the security token
webexConnect.setSecurityToken("your_token_here")

// Get the shared instance of WebexConnect
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
// Set the security token
[webexConnect setSecurityToken:@"your_token_here"]; 

registerSecurityTokenErrorDelegate(:)

This method allows developers to register an object which implements the SecurityTokenExceptionListener interface to listen for Security Token related exceptions which occur from internal (indirect) Gateway API calls.

Syntax func registerSecurityTokenErrorDelegate(_ delegate: SecurityTokenErrorDelegate)

Parameters

Sample Code:

// Get the shared instance of WebexConnect
let webexConnect = WebexConnectProvider.instance
// Create your delegate conforming to SecurityTokenErrorDelegate
let delegate = MySecurityTokenErrorDelegate()
// Register the delegate
webexConnect.registerSecurityTokenErrorDelegate(delegate)

// Get the shared instance of WebexConnect
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
// Create your delegate conforming to SecurityTokenErrorDelegate
MySecurityTokenErrorDelegate *delegate = [[MySecurityTokenErrorDelegate alloc] init];
// Register the delegate
[webexConnect registerSecurityTokenErrorDelegate:delegate];

unregisterSecurityTokenErrorDelegate (:)

This method unregisters a listener from handling security token errors.

Syntax func unregisterSecurityTokenErrorDelegate(_ delegate: SecurityTokenErrorDelegate)

Parameters 

Sample Code

// Get the shared instance of WebexConnect
let webexConnect = WebexConnectProvider.instance
// Unregister your delegate
webexConnect.unregisterSecurityTokenErrorDelegate(delegate)

// Get the shared instance of WebexConnect
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
// Unregister your delegate
[webexConnect unregisterSecurityTokenErrorDelegate:delegate];

updateProfile(param:with:completionHandler:)

This method updates the device profile parameter identified by DeviceProfileParam with a new value.

Syntax func updateProfile(param: DeviceProfileParam, with value: String, completionHandler: @escaping ([String: Any]?, Error?) -> Void)

Parameters

Precondition: This method can be used only if the SDK is already started and the device profile is registered.

Sample Code:

// Get the shared instance of WebexConnect
let webexConnect = WebexConnectProvider.instance
// Update the userId in the device profile
webexConnect.updateProfile(param: .userId, with: "newUserId") { result, error in
    if let error = error {
        print("Update failed: \(error.localizedDescription)")
    } else {
        print("Update successful: \(String(describing: result))")
    }
}

// Get the shared instance of WebexConnect
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
// Update the userId in the device profile
[webexConnect updateProfileWithParam:DeviceProfileParamUserId with:@"newUserId" completionHandler:^(NSDictionary *result, NSError *error) {
    if (error) {
        NSLog(@"Update failed: %@", error.localizedDescription);
    } else {
        NSLog(@"Update successful: %@", result);
    }
}];

removeProfile(param:completionHandler:)

This methods removes the current userId or customerId from the device profile.

Syntax: func removeProfile(param: DeviceProfileParam, completionHandler: @escaping ([String: Any]?, Error?) -> Void)

Parameters

Precondition: This method can be used only if the SDK is already started and the device profile is registered

Sample Code:

// Get the shared instance of WebexConnect
let webexConnect = WebexConnectProvider.instance
// Remove the userId from the device profile
webexConnect.removeProfile(param: .userId) { result, error in
    if let error = error {
        print("Remove failed: \(error.localizedDescription)")
    } else {
        print("Remove successful: \(String(describing: result))")
    }
}

// Get the shared instance of WebexConnect
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
// Remove the userId from the device profile
[webexConnect removeProfileWithParam:DeviceProfileParamUserId completionHandler:^(NSDictionary *result, NSError *error) {
    if (error) {
        NSLog(@"Remove failed: %@", error.localizedDescription);
    } else {
        NSLog(@"Remove successful: %@", result);
    }
}];	

publishEvent(_ : completionHandler:)

This method publishes your custom events info to the Webex Connect platform.

Syntax: func publishEvent(_ event: [String: Any], completionHandler: @escaping ([String: Any]?, Error?) -> Void)

Parameters

Precondition:This method can be used only if the SDK is already started and the device profile is registered.

Sample Code:

// Get the shared instance of WebexConnect
let webexConnect = WebexConnectProvider.instance
// Create a custom event dictionary
let event: [String: Any] = ["eventType": "custom", "value": 123]
// Publish the event
webexConnect.publishEvent(event) { result, error in
    if let error = error {
        print("Publish event failed: \(error.localizedDescription)")
    } else {
        print("Event published: \(String(describing: result))")
    }
}

// Get the shared instance of WebexConnect
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
// Create a custom event dictionary
NSDictionary *event = @{ @"eventType": @"custom", @"value": @123 };
// Publish the event
[webexConnect publishEvent:event completionHandler:^(NSDictionary *result, NSError *error) {
    if (error) {
        NSLog(@"Publish event failed: %@", error.localizedDescription);
    } else {
        NSLog(@"Event published: %@", result);
    }
}];

setLogger(:)

Sets a logger for the SDK. Use this method to configure the SDK with a logger implementation. You have the option to choose between a ConsoleLogger for immediate console output or a FileLogger for storing log messages in a file.

Syntax: func setLogger(_ logger: Logger)

Parameters

Sample Code:

// Get the shared instance of WebexConnect
let webexConnect = WebexConnectProvider.instance
// Create console/file logger instance
let logger = ConsoleLogger(logType: .fault)
// Set the logger
webexConnect.setLogger(logger)

// Get the shared instance of WebexConnect
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
// Create ConsoleLogger/FileLogger instance
ConsoleLogger *logger = [[ConsoleLogger alloc] initWithLogType:OS_LOG_TYPE_FAULT];
// Set the logger
[webexConnect setLogger:logger];

Config

This class holds the configuration information that is used to initialize the SDK.

Properties

Methods

init(appId: clientKey: serverDomain: environment: groupIdentifier:)

Syntax: init(appId: String, clientKey: String, serverDomain: String? = nil, environment: Environment = .uk,groupIdentifier: String? = nil)

Parameters

DeviceProfile

The DeviceProfile represents the profile of a device associated with a user in the application. It contains various properties that store information related to the device, and user. An DeviceProfileinstance should be instantiated to register a device profile.

The developer can choose to register the device profile with a deviceId only or with a deviceId and an appUserId. User can generate a unique/own device ID or can choose the defaultDeviceId provided by the SDK. If the user chooses to register a device profile with the deviceId only, the backend will automatically generate an appUserId. The current device profile is accessible via the Webex Connect class.

Properties

Methods

init(deviceId:userId::isGuest:)

This initializer method is used to create an instance of the DeviceProfile with the provided parameters.

Syntax: public init(deviceId: String, userId: String? = nil, isGuest: Bool = false)

Parameters

defaultDeviceId()

Syntax: static func defaultDeviceId() -> String

Return Value: The default device ID.

Logger

The Logger protocol defines a basic interface for implementing loggers in the system. It provides methods for logging messages with a specified log type, tag, and message.

Syntax: protocol Logger

Methods

log(logType:tag:message:args:)

Logs a message with the specified log type, tag, message, and optional arguments.

Syntax: func log(logType: OSLogType, tag: String, message: String, args: [String])

Parameters

shouldLog(logType:)

Checks if the logger should log a message with the specified log type.

Syntax: func shouldLog(for logType: OSLogType) -> Bool

Parameters 

Properties

filter

The log level filter for the logger.

Syntax: var filter: OSLogType { get }

Console Logger

The ConsoleLogger class implements the Logger protocol that logs messages to the console.

Syntax: class ConsoleLogger: Logger

Properties

filter

Gets the log type currently set as the filter for the logger.

Syntax: var filter: OSLogType { get }

Return Value:The log type currently set as the filter for the logger.

Methods

init(logType:)

Initializes a logger with the specified log type.

Syntax: init(logType: OSLogType)

Parameters

log(logType:tag:message:args:)

Logs a message with the specified log type, tag, message, and optional arguments.

Syntax: func log(logType: OSLogType, tag: String, message: String, args: [String])

Parameters

shouldLog(logType:)

Checks if the logger should log a message with the specified log type.

Syntax: func shouldLog(for logType: OSLogType) -> Bool

Parameters

File Logger

A Logger implementation that logs messages to a file.

Syntax: class FileLogger

Properties

filter

Gets the log type currently set as the filter for the logger.

Syntax: var filter: OSLogType { get }

Return Value: The log type currently set as the filter for the logger.

Methods

init(filter:outputDir:retentionDays:)

Creates a FileLogger instance with the specified parameters.

Syntax:init( filter: OSLogType, outputDir: URL, retentionDays: Int)

Return Value:The created FileLogger instance.

Parameters

log(logType:tag:message:args:)

Logs a message with the specified log type, tag, message, and optional arguments.

Syntax: func log(logType: OSLogType, tag: String, message: String, args: [String])

Parameters

shouldLog(logType:)

Checks if the logger should log a message with the specified log type.

Syntax: func shouldLog(for logType: OSLogType) -> Bool

Parameters

Environment

The Environment struct represents the environments in which an application can operate. This struct is used to specify the target server domain based on the environment.

Syntax: struct Environment

📘

Note

Starting with iOS SDK v3.0.4, the environment values has changed.

• If you are using an SDK version less than v3.0.4, you must use uppercase environment values (e.g., UK, US, CA, LDN).
• If you are using SDK version v3.0.4 or later, you must use lowercase environment values (e.g., uk, us, ca, ldn).

Properties

Methods

init(rawValue:)

Initializes an Environment instance with the provided raw value.

Syntax: init(rawValue: String)

Parameters

SecurityTokenErrorDelegate

The delegate interface for security token error events.

Syntax: protocol SecurityTokenErrorDelegate : AnyObject

Methods

didReceiveTokenError(error:)

Called when a security token error occurs.

Syntax: func didReceiveTokenError(error: Error)

ErrorCode

This enumeration describes different error codes of the SDK.

DeviceProfileParam

This enumeration describes the different device profile parameters supported for update and remove operations.