iOS SDK Migration Guide: 2.x to 3.x

This document details the necessary changes required when migrating from iOS SDK version 2.x to version 3.x.

The Webex Connect iOS SDK version 3.0.0 is a major rewrite of version 2.x. This SDK is structured into modular components, each designed to offer specific functionality. Version 3.0.0 of the SDK is developed in Swift 5 and requires iOS 13 or later.

📘

Note

The current version of the modular SDK does not migrate registration data, hence we recommend continuing to use the existing 2.x version. Data migration will be added in a future version, helping to ensure a smooth transition to the modular SDK.

Please refer to the table below for more details about each module and its functionality. This information will help you understand what's available in each module and decide which modules you want to integrate into your application.

ModuleDescription
WebexConnectCore (Mandatory)The WebexConnectCore module is the foundation of the Webex Connect SDK. It provides essential functionality that all other modules depend on, including initialization, configuration, registration, and shared utilities.
WebexConnectPushThe WebexConnectPush module enables your application to receive and handle push notifications. It abstracts the underlying push notification service, providing customized support for notification management.
WebexConnectInAppMessagingThe WebexConnectInAppMessaging module offers both one-way and two-way messaging capabilities for your app.

Prerequisites

ComponentRequirement
iOS Operating SystemiOS 13 and above
SoftwareXcode Latest Version
Webex Connect iOS SDK
AccountsA valid Apple Developer account.
A valid Google account (required only if you're using FCM push services).
An active Webex Connect account.

Integration

The following sections outline the most common tasks required to integrate the Webex Connect SDK into your iOS application. While many methods remain similar to the previous version of the SDK, many of the classes and interfaces have changed, please refer the mapping tables at the end of this guide for more details.

Below are sample codes to help you understand better. In previous versions, initializing the Connect Core SDK would automatically enable all modules at once. In version 3.0, you can access and manage the Core, Push, and InApp modules independently, allowing for more granular control.

Integrating SDK via Cocoa Pods

Remove v2.x pod file:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '13.0' 
target 'MyWebexConnectApp' do     
pod 'WebexConnectCoreSDKFull'
end
target 'MyWebexConnectAppServiceExtension' do       
pod 'WebexConnectNotificationServiceExtension'  
end
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '13.0' 
target 'MyWebexConnectApp' do                 
pod 'WebexConnectCoreSDKLite'
end
target 'MyWebexConnectAppServiceExtension' do       
pod 'WebexConnectNotificationServiceExtension'  
end

Add v3.x pod file:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '13.0'
target 'MyWebexConnectApp' do
pod 'WebexConnectCore'
pod 'WebexConnectPush'
pod 'WebexConnectInAppMessaging'
end
target 'MyWebexConnectAppServiceExtension' do
pod 'WebexConnectNotificationServiceExtension'
end

📘

Note

For information on installing the SDKs manually or via SPM, please refer to our Quick Start guide.

Initialize the SDK

The process for Initializing the device is the same on v3.x as it is on v2.x, but class names have changed.

Remove v2.x registration code:

NSError *error;
[IMIconnect startup:&error];

Replace with v3.x code:

private let webexConnect = WebexConnectProvider.instance
webexConnect.startup { error in
  if error == nil {
    print("SDK started successfully")
  } else {
    print("Error starting up the SDK: \(error)")
  }
}
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
[webexConnect startupWithCompletion:^(NSError *error) {
    if (error == nil) {
        NSLog(@"SDK started successfully");
    } else {
        NSLog(@"Error starting up the SDK: %@", error);
    }
}];

Device registration

The process for device registration is the same on v3.x as it is on v2.x, but class names have changed.

Remove v2.x registration code:

if (![IMIconnect isRegistered])
{
  //Instantiate a device profile, this example uses a default device id implementation, but you may use an alternative.
  ICDeviceProfile *deviceProfile = [[ICDeviceProfile alloc] initWithDeviceId:[ICDeviceProfile defaultDeviceId] appUserId:"YOUR_USER_ID"];
  [IMIconnect registerWithDeviceProfile:deviceProfile completionHandler:^(NSDictionary *response, NSError *error)
    {
      if (error == nil)
      {
        //Device was registered successfully
      }
      else
      {
        //Device registration failed, query error for reason information
      }
    }];
}

Replace with v3.x code:

private let webexConnect = WebexConnectProvider.instance
var deviceProfile = DeviceProfile(deviceId: DeviceProfile.defaultDeviceId(), userId: "your user id")
webexConnect.register(with: deviceProfile) { response, error in
  if error != nil {
    //Device registration failed, query error for reason information
  } else {
    //Device registered successfully
  }
}
id<WebexConnect> webexConnect = [WebexConnectProvider instance];
DeviceProfile *deviceProfile = [[DeviceProfile alloc] initWithDeviceId:[DeviceProfile defaultDeviceId] userId:@"your user id"];
[webexConnect registerWithDeviceProfile:deviceProfile completion:^(id response, NSError *error) {
    if (error != nil) {
        // Device registration failed, query error for reason information
    } else {
        // Device registered successfully
    }
}];

Push Notifications

Remove the subclassing from ICAppDelegate. Remove all the push message related methods.

Remove 2.x code

@interface AppDelegate : ICAppDelegate <UIApplicationDelegate>

Replace 3.x code

let push = PushMessagingProvider.instance
push.pushMessagingDelegate = self //self is the class where developer needs to handle push messaging delegates.

push.actionsDelegate = self //self is the class where developer needs to handle action delegates.
push.setAppDelegateMethodSwizzlingEnabled(true) //You can pass false, if you want to disable method swizzling for app delegates methods.
push.setNotificationCenterMethodSwizzlingEnabled(true) //You can pass false, if you want to disable method swizzling for notification center..

Push Messaging Delegate

The v2.x SDK emitted incoming push through the ICMessagingDelegate as ICMessage objects. The v3.x SDK emits push as PushMessage objects through the PushMessagingDelegate.

Remove with v2 code:

#import "ICMessaging.h"    
@interface MyMessagingDelegate : NSObject <ICMessagingDelegate>
    
@end 
  
@implementation MyMessagingDelegate  

-(id)init
{
  if (self = [super init])
  {
    [ICMessaging shared].delegate = self;
  }
    
  return self;
}

- (void)didReceiveMessage:(ICMessage *)message 
{ 
	//Invoked as new messages are received  
}  

- (void)didChangeConnectionStatus:(ICConnectionStatus)connectionStatus 
{
	//Invoked when the status of the In App Messaging connection changes.
}   

@end

Replace with v3 code:

//MARK: PushMessagingDelegate
class PushMessagingViewModel: PushMessagingDelegate {   
func didReceiveMessage(message: WebexConnectPush.PushMessage, fromTap: Bool) {     
let logMessage = "PushMessagingDelegate didReceiveMessage: \(message.message ?? "nil") transId: \(message.transactionId ?? "nil")"
        print(logMessage)
  
        //Handle incoming message
    }
}

//MARK: PushActionsDelegate
extension AppDelegate: PushActionsDelegate {  
func handleAction(_ action: String, withIdentifier identifier: String, forMessage message: WebexConnectPush.PushMessage, responseInfo: [String : 
Any]?) -> Bool {
        print("handleAction \(action) withIdentifier: \(identifier), responseInfo: \(String(describing: responseInfo))")
        
return 
true
    }
}
#pragma mark PushMessagingDelegate
@interface PushMessagingViewModel : NSObject <PushMessagingDelegate>
@end
@implementationPushMessagingViewModel - (void)didReceiveMessage
    : (WebexConnectPushPushMessage *)message fromTap : (BOOL)fromTap {
  NSString *logMessage =
      [NSString stringWithFormat:
                    @"PushMessagingDelegate didReceiveMessage: %@ transId: %@",
                    message.message ?: @"nil", message.transactionId ?: @"nil"];
  NSLog(@"%@", logMessage);
//Handle incoming message
}
@end

#pragma mark PushActionsDelegate
@implementation AppDelegate (PushActionsDelegate)
- (BOOL)handleAction:(NSString *)action
      withIdentifier:(NSString *)identifier
          forMessage:(WebexConnectPushPushMessage *)message
        responseInfo:(NSDictionary<NSString *, id> *)responseInfo {
  NSLog(@"handleAction %@ withIdentifier: %@, responseInfo: %@", action,
        identifier, responseInfo);
  return YES;
}
@end

InApp Messaging

Message Store

The ICDefaultMessageStore found in v2.x has been renamed to DefaultMessageStore in v3.x, and is set using the InAppMessagingProvider.messageStore property.

Remove v2.x code:

- (instancetype)initWithPassword:(NSString *)password

Replace with v3.x code:

let messageStore = DefaultMessageStore(password: "DefaultMessageStore") 
InAppMessagingProvider.instance.messageStore = messageStore 
InAppMessagingProvider *inApp = [InAppMessagingProvider instance]; 
DefaultMessageStore *messageStore = [[DefaultMessageStore alloc] initWithPassword:@"DefaultMessageStore"]; 
[inApp setMessageStore:messageStore]; 

Intercepting incoming messages

The v2.x SDK emitted incoming messages and connection status changes through the ICMessagingDelegate protocol. The v3.x SDK uses InAppMessagingDelegate protocol.

Remove v2.x code:

Remove any code that uses ICMessagingDelegate protocol for handling incoming messages and connection status changes.

#import "ICMessaging.h"    
@interface MyMessagingDelegate : NSObject <ICMessagingDelegate>
    
@end 
  
@implementation MyMessagingDelegate  

-(id)init
{
  if (self = [super init])
  {
    [ICMessaging shared].delegate = self;
  }
    
  return self;
}

- (void)didReceiveMessage:(ICMessage *)message 
{ 
	//Invoked as new messages are received  
}  

- (void)didChangeConnectionStatus:(ICConnectionStatus)connectionStatus 
{
	//Invoked when the status of the In App Messaging connection changes.
  }   

@end

Replace with v3.x code:

let inApp = InAppMessagingProvider.instance
inApp.delegate = self

// Handle received In-App messages
func didReceiveInAppMessage(message: InAppMessage) {
  // Process the received message
  print("Received in-app message: (message)")
  // Implement additional message handling logic as needed
}

func didChangeConnectionStatus(_ connectionStatus: ConnectionStatus) {
  //didChangeConnectionStatus method monitors the connection status using WebexConnectInAppMessaging.ConnectionStatus and updates the application's UI or internal state based on the current status
}
id<InAppMessaging> inApp = [InAppMessagingProvider instance];
inApp.delegate = self;

// Handle received In-App messages
- (void)didReceiveInAppMessage:(InAppMessage *)message {
  // Process the received message
  NSLog(@"Received in-app message: %@", message);
  // Implement additional message handling logic as needed
}

- (void)didChangeConnectionStatus:(ConnectionStatus)connectionStatus {
  
  // didChangeConnectionStatus method monitors the connection status using ConnectionStatus and updates the application's UI or internal state based on the current status.
  
}

Class Name Changes, Method Name Changes, and New Properties

The following tables detail the class and interface mappings between v2.x and v3.x, please refer to these tables to help transition the rest of your codebase.

Note that in v3.x, we have replaced the IMIconnect class with WebexConnect class. Please refer to the method-specific documentation relevant to your application to understand the changes and update your implementation accordingly.

Core Module

Class Name mapping from 2.x to 3.x

Push Module

InApp Messaging Module

By following the steps outlined in this document and updating your code to reflect the changes in class names, method names, and new properties, you should be able to successfully migrate from the monolithic v2.x SDK to the modular v3.x SDK. Please ensure that you thoroughly test your application after making these changes to confirm that all functionalities are working as expected.