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()

This method initializes the SDK, reading configuration from the configuration file (IMIconnect.plist).

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

Parameters

Sample Code

let webexConnect = WebexConnectProvider.instance
webexConnect.startup { error in
  if error == nil {
    print("sdk started")
  } else {
    print("startup failed", error?.localizedDescription ?? "")
  }
}

id<WebexConnect> webexConnect = [WebexConnectProvider instance]; 
[webexConnect startupWithCompletionHandler:^(NSError * error) {   
  if (error == nil) { 
        NSLog(@"SDK started"); 
    } else { 
        NSLog(@"Startup failed: %@", error.localizedDescription ?: @""); 
    } 
}]; 

startup(config:completionHandler)

This method initializes the SDK using the passed configuration.

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

Parameters

Sample Code

let webexConnect = WebexConnectProvider.instance
let config = Config.init(appId: "appID", clientKey: "clientKey")
webexConnect.startup(config: config) { error in
  if error == nil {
    print("sdk started")
  } else {
    print("startup failed", error?.localizedDescription ?? "")
  }
}

id<WebexConnect> webexConnect = [WebexConnectProvider instance];  
Config *config = [[Config alloc] initWithAppId:@"appID" clientKey:@"clientKey" serverDomain:nil environment: Environment.UK]; 
   [webexConnect startupWithConfig:config completionHandler:^(NSError * error) {    if (error == nil) { 
        NSLog(@"SDK started"); 
    } else { 
        NSLog(@"Startup failed: %@", error.localizedDescription ?: @""); 
    } 
}]; 

startup(with:launchOptions:)

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 IMIconnectConfiguration.plist is not used.

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

Parameters

Sample Code:

let webexConnect = WebexConnectProvider.instance
let config = Config.init(appId: "appID", clientKey: "clientKey")
webexConnect.startup(config: config, launchOptions: nil, connectionOptions: nil) { error in
  if error == nil {
    print("sdk started")
  } else {
    print("startup failed", error?.localizedDescription ?? "")
  }
}

id<WebexConnect> webexConnect = [WebexConnectProvider instance];  
Config *config = [[Config alloc] initWithAppId:@"appID" clientKey:@"clientKey" serverDomain:nil environment: Environment.UK]; 
[webexConnect startupWithConfig:config launchOptions:nil connectionOptions:nil completion:^(NSError *error) { 
    if (error == nil) { 
        NSLog(@"SDK started"); 
    } else { 
        NSLog(@"Startup failed: %@", error.localizedDescription ?: @""); 
    } 
}]; 

shutdown()

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:

let webexConnect = WebexConnectProvider.instance
webexConnect.shutdown { error in
  if error == nil {
    print("sdk shut down")
  } else {
    print("shut down failed", error?.localizedDescription ?? "")
  }
} 

id<WebexConnect> webexConnect = [WebexConnectProvider instance];  
[webexConnect shutdown:^(NSError *error) { 
    if (error == nil) { 
        NSLog(@"SDK shut down"); 
    } else { 
        NSLog(@"Shut down failed: %@", error.localizedDescription ?: @""); 
    } 
}]; 

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

let webexConnect = WebexConnectProvider.instance
let started = webexConnect.isStarted

id<WebexConnect> webexConnect = [WebexConnectProvider instance];
BOOL started = [webexConnect isStarted]; 

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:

let webexConnect = WebexConnectProvider.instance
var deviceProfile = DeviceProfile(deviceId: DeviceProfile.defaultDeviceId(), userId: "userID")
webexConnect.register(deviceProfile: deviceProfile) { response, error in
  print("register response:\(String(describing: response)), error:", error ?? "")
}

id<WebexConnect> webexConnect = [WebexConnectProvider instance];  
DeviceProfile *deviceProfile = [[DeviceProfile alloc] initWithDeviceId:[DeviceProfile defaultDeviceId] userId:@”userID”];  
[webexConnect registerWithDeviceProfile:deviceProfile completion:^(id response, NSError *error) {  
NSLog(@"Register response: %@, error: %@", response ?: @"nil", error.localizedDescription ?: @"nil");  
}]; 

deviceProfile

This method retrieves the currently registered device profile.

Syntax var deviceProfile: DeviceProfile? { get }

Return Value: The current registered device profile.

Sample Code:

let webexConnect = WebexConnectProvider.instance 
let deviceProfile = webexConnect.deviceProfile 

id<WebexConnect> webexConnect = [WebexConnectProvider instance];  
DeviceProfile * deviceProfile = [webexConnect deviceProfile]; 

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:

let webexConnect = WebexConnectProvider.instance 
let isRegistered = webexConnect. isRegistered

id<WebexConnect> webexConnect = [WebexConnectProvider instance];  
BOOL isRegistered = [webexConnect isRegistered]; 

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:

let webexConnect = WebexConnectProvider.instance
webexConnect.unregister { response, error in
  print("unregister response:(String(describing: response)), error:", error ?? "")
}

id<WebexConnect> webexConnect = [WebexConnectProvider instance];  
[webexConnect unregisterWithCompletion:^(id response, NSError *error) {  
NSLog(@"Unregister response: %@, error: %@", response ?: @"nil", error.localizedDescription ?: @"nil");  
}]; 

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:

let webexConnect = WebexConnectProvider.instance 
let sdkVersion = webexConnect. sdkVersion 

id<WebexConnect> webexConnect = [WebexConnectProvider instance];  
String *sdkVersion = [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:

let webexConnect = WebexConnectProvider.instance 
webexConnect.setSecurityToken(“Your security Token”)

id<WebexConnect> webexConnect = [WebexConnectProvider instance];  
String *sdkVersion = [webexConnect sdkVersion]; 

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:

let webexConnect = WebexConnectProvider.instance 
webexConnect.registerSecurityTokenErrorDelegate(self) 

id<WebexConnect> webexConnect = [WebexConnectProvider instance];  
[webexConnect registerSecurityTokenErrorDelegate:self]; 

unregisterSecurityTokenErrorDelegate (:)

This method unregisters a listener from handling security token errors.

Syntax func unregisterSecurityTokenErrorDelegate(_ delegate: SecurityTokenErrorDelegate)

Parameters 

Sample Code

let webexConnect = WebexConnectProvider.instance 
webexConnect.unregisterSecurityTokenErrorDelegate(self)

id<WebexConnect> webexConnect = [WebexConnectProvider instance];
[webexConnect unregisterSecurityTokenErrorDelegate:self];

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:

let webexConnect = WebexConnectProvider.instance
webexConnect.updateProfile(param: .userId, with: "newUserId") {
  response, error in
  print("update profile response:\(String(describing: response)), error:", error ?? "")
}

id<WebexConnect> webexConnect = [WebexConnectProvider instance];  
[webexConnect updateProfileWithParam:DeviceProfileParamUserId value:@"newUserId" completion:^(id response, NSError *error) 
 { NSLog(@"Update profile response: %@, error: %@", response ?: @"nil", error.localizedDescription ?: @"nil"); 
 }]; 

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:

let webexConnect = WebexConnectProvider.instance
webexConnect.removeProfile(param: .userId) { response, error in
  print("remove profile response:\(String(describing: response)), error:", error ?? "")
}

id<WebexConnect> webexConnect = [WebexConnectProvider instance];  
[webexConnect removeProfileWithParam:DeviceProfileParamUserId completion:^(id response, NSError *error) { 
NSLog(@"Remove profile response: %@, error: %@", response ?: @"nil", error.localizedDescription ?: @"nil");  
}]; 

publishEvent(event: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:

let webexConnect = WebexConnectProvider.instance 
let eventJson = ["name": "sample"] 
webexConnect.publishEvent(eventJson) { response, error in             
print("publish event response:\(String(describing: response)), error:", error ?? "") 
} 

id<WebexConnect> webexConnect = [WebexConnectProvider instance];  
NSDictionary *eventJson = @{"name": "sample"}; // Replace with your actual JSON dictionary [webexConnect publishEvent:eventJson completion:^(id response, NSError *error) {  
NSLog(@"Publish event response: %@, error: %@", response ?: @"nil", error.localizedDescription ?: @"nil");  
}]; 

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:

let webexConnect = WebexConnectProvider.instance 
let logDirectoryURL = //Your log Directory URL 
let retentionDays = // Your retention Days 
let fileLogger = FileLogger.create(filter: .fault, outputDir: logDirectoryURL, retentionDays: retentionDays) 
webexConnect.setLogger(fileLogger) 

WebexConnect *webexConnect = [WebexConnectProvider instance];  
NSURL *logDirectoryURL = // Your log directory URL here  
NSInteger retentionDays = // Your retention days here  
FileLogger *fileLogger = [FileLogger createWithFilter:LogLevelFault outputDir:logDirectoryURL retentionDays:retentionDays];  
[webexConnect setLogger:fileLogger]; 

Config

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

Properties

Methods

init(appId: clientKey: serverDomain: environment:)

Initialises an Config instance with the provided information.

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

init(appId: String, clientKey: String, serverDomain: String? = nil, environment: Environment = .UK)

Initialises an Config instance with the provided information.

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

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

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.