Migrate from Chat 1.0

Learn how to migrate to the Kustomer Chat 2.0 iOS SDK from Chat 1.0.

This guide explains the key changes your team needs to make to migrate to the Kustomer Chat 2.0 (and later) iOS SDKs from earlier SDK versions.

We've listed the iOS SDK API calls you'll need to update for the migration below. Each entry provides brief descriptions and examples of the changes.

📘

We've migrated our SDK to Swift!

With ABI Stability available for Swift 5, the Kustomer team decided to release the iOS SDK for Kustomer Chat 2.0 as a modern Swift library. We hope our updated Swift APIs make it easier for you to develop with our iOS SDK.

If you need to support the Kustomer Chat SDK in an Objective-C application see Use the SDK with Objective-C.

Install chat

Apply the following change in the UIApplicationDelegate method of your project.

To learn more, see Installation.

#import <Kustomer/Kustomer.h>

static NSString *const kKustomerAPIKey = @"YOUR_API_KEY";

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [Kustomer initializeWithAPIKey:kKustomerAPIKey];
}
import KustomerChat

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
  Kustomer.configure(apiKey: "YOUR_API_KEY")
}

Open chat

To learn more, see Installation: Open Kustomer chat.

KustomerViewController *kustomerViewController = [[KustomerViewController alloc] init];
[self presentViewController:kustomerViewController animated:YES completion:nil];
// or
[Kustomer presentSupport];
Kustomer.show()

Upload images over chat

Add app privacy descriptions to allow users to upload images over chat messages. Kustomer Chat hides the button to attach images when these app privacy descriptions are absent from your Info.plist file for your project in Xcode.

To learn more, see Installation: Allow file uploads over chat.

NSCameraUsageDescription is required to enable taking a photo
NSPhotoLibraryUsageDescription is required to enable picking from your Camera Roll
NSPhotoLibraryAddUsageDescription is required to save images to your Photos Library
Privacy - Camera Usage Description
Privacy - Media Library Usage Description
Privacy - Microphone Usage Description
Privacy - Photo Library Usage Description

Use chatAttributes

You can present new chat conversations with chatAttributes key-value pairs.

Message to start a new conversation

KUSChatAttributes chatAttributes = @{
    kKUSMessageAttribute: @"MESSAGE"
};

[Kustomer presentSupportWithAttributes:chatAttributes];
Kustomer.openNewChat(initialMessages: ["Hello","How can we help?"])

// New: callback for when the conversation is created
Kustomer.openNewChat(
  initialMessages: ["Hello","How can we help?"],
  afterCreateConversation: { conversation in
    print("New conversation created. Conversation id is \(conversation.id)")
  })
)

Custom Conversational Form ID

Conversational Assistants replace Custom Forms in Kustomer Chat 2.0.

To learn more, see Introduction to Conversational Assistants.

KUSChatAttributes chatAttributes = @{
    // Custom form id, if not specified then SDK will use the conversational assistant form specified on the admin panel
    // You can access the id in Kustomer in Settings > Channels > Chat > Conversational Assitant
    kKUSFormIdAttribute: @"FORM_ID"
};
[Kustomer presentSupportWithAttributes:chatAttributes];
//Form IDs have been replaced with our new chat assistant
Kustomer.options.activeAssistant = .orgDefault

//These can be accessed by the admin panel via Settings > Kustomer IQ > Conversational Assistants

Custom attributes for new conversations

KUSChatAttributes chatAttributes = @{
    // Attach custom attributes to the user's next new conversation
    // These key-value pairs must be enabled on the Conversation Klass in Kustomer in Settings > Platform > Klasses > Conversation.
    kKUSCustomAttributes: @{
        @"customAttributeStr": @"value"
    }
};
[Kustomer presentSupportWithAttributes:chatAttributes];
let chatAttributes = ["customAttributeStr":"value"]

let after = { conversation in
  Kustomer.chatProvider.describeConversation(conversationId: conversation.id!, attributes: chatAttributes) { result in
    switch result {
    case .success:
      print("success")
    case .failure(let error):
      print(error.localizedDescription)
    }
  }
}

Kustomer.openNewChat(afterCreateConversation: after)

Custom attributes for Business Schedule ID

To learn more, see Business Schedules in the Kustomer Help Center.

KUSChatAttributes chatAttributes = @{
    // Custom schedule id, if not specified then SDK will use the schedule id specified on the admin panel
    // This can be access by an admin panel via Administration > Business Schedules
    kKUSScheduleIdAttribute: @"SCHEDULE_ID"
};
[Kustomer presentSupportWithAttributes:chatAttributes];
// Custom schedule id, if not specified then SDK will use the schedule id specified on the admin panel
Kustomer.options.businessScheduleId = "123456"

Kustomer.chatProvider.reloadChatSettings({ error in
  if error == nil {
    DispatchQueue.main.async {
      Kustomer.show()
    }
  } else {
    print(error?.localizedDescription)
  }
})

// Every time you show the Kustomer UI it will now use this new business schedule ID.

Show the Knowledge Base

[Kustomer presentKnowledgeBase];
Kustomer.show(preferredView: .knowledgeBase)

Open a Knowledge Base article

See Open Knowledge Base article by id.

// Convenience method that will present a specific web page interface
[Kustomer presentCustomWebPage:@"https://www.support.acme.com/specific-article-url"];
Kustomer.showKbArticle(id: "1234")

Identify or log in a customer

We've deprecated identifyCurrentCustomer for Kustomer Chat 2.0. Use logIn() or logOut() followed by logIn() instead.

To learn more, see Authentication.

[Kustomer identify:@"SECURE_ID_HASH"];
Kustomer.identifyCurrentCustomer(jwt: "SECURE_ID_HASH", { result in
  switch result {
  case .success:
    print("Success")
  case .failure(let error):
    print(error.localizedDescription)
  }
})

Log out or reset a chat session

We've deprecated identifyCurrentCustomer for Kustomer Chat 2.0. Use logIn() or logOut() followed by logIn() instead.

// Resets the user session and clears customer access to any existing chats from the device.
[Kustomer resetTracking];
Kustomer.logOut({ error in
	// If you have push notifications enabled, logOut may error.
  // If you do not have push notifications enabled, error will always be nil.
})

Describe a customer

Add custom attributes to a Customer object.

To learn more, see Describe Customer.

KUSCustomerDescription *customerDescription = [[KUSCustomerDescription alloc] init];
customerDescription.email = @"[email protected]";
customerDescription.custom = @{ @"customAttributeStr": @"value" };
[Kustomer describeCustomer:customerDescription];
Kustomer.chatProvider.describeCurrentCustomer(phone:"12121234567") { result in
  switch result {
    case .success:
      print("ok")
    case .failure(let error):
      print(error)
  }
}

Describe a conversation

Add custom attributes to a Conversation object.

To learn more, see Describe Conversation.

// Attach custom attributes to the user's most recent conversation (or the first one they create)

[Kustomer describeConversation:@{ @"customAttributeStr" : @"value" }];
// Attach custom attributes to a conversation by ID
// Get a conversation's ID using callbacks on openNewChat, or by using a KUSChatListener

Kustomer.chatProvider.describeConversation(id:"ID", ["favoriteNumberNum":100]) { result in
  switch result {
    case .success:
      print("ok")
    case .failure(let error):
      print(error)
  }
}

Mark navigation of user

The Chat 1.0 SDK allowed you to mark the user when they navigated to a new page. This feature is no longer supported in the Chat 2.0 (and later) SDKs.

/*
 Mark the user as having navigated to a new page. By marking the user's progress around the app, you will be able to create proactive conversational campaigns that can be triggered as a result of the user's progress in your application flow.
*/
- (void)viewDidAppear:(BOOL)animated
{
    [super viewDidAppear:animated];

    // Track the current page on appearance
    [Kustomer setCurrentPageName:@"Home"];
}
Not supported

Check chat availability status

You can check your chat availability status and communicate chat availability with customers. If you have business hours configured, or , along with within Business Hours and outside of Holidays settings asynchronously.

[Kustomer isChatAvailable:^(BOOL success, BOOL enabled) {
    // success variable shows if the API call was successful or not.
    // enabled represents chat management settings and within Business Hours and outside of Holidays.
    // enabled flag is only valid if success flag is true as well.
}];
Kustomer.isChatAvailable { available in
	if available {
  	print("chat is available")
  } else {
  	print("chat is unavailable. outside of business hours, or a holiday, etc.")
  }
}

For non-business hours and for when chat is turned off, you can remove the chat button from your site or ask customers to contact support over another channel (for example, email).

/*
 Show/Hide the "New Conversation" button in closed chat. By default, "Start New Conversation" button will appear in closed chat listing. You can update the settings by this method.
*/
[Kustomer hideNewConversationButtonInClosedChat:YES];
var options = KustomerOptions()
options.hideNewConversationButtonInClosedChat = true
Kustomer.configure(apiKey: "API KEY", options: options, launchOptions: launchOptions)

Observe unread message count

/*
 Return the current count of un-read messages. It might not be immediately available. 
*/
[Kustomer unreadMessageCount];
let count = Kustomer.chatProvider.openConversationCount()

// Can also observe the unread count in real time using a KUSChatListener
// https://kustomer.readme.io/docs/additional-apis-1#observe-unread-count

Override the conversation form directly from the SDK

You can set the conversation form ID to override the conversation form directly from the SDK.

Kustomer Chat 2.0 uses conversational assistants instead of conversational forms. To learn more, see Introduction to Conversational Assistants in the Kustomer Help Center.

[Kustomer setFormId:FORM_ID];
Conversational forms not supported in Kustomer Chat 2.0. Instead, use a conversational assistant.

Change the default language

The Kustomer iOS SDK (1.x and 2.0 and later) use the mobile device language as the default language. You can override this default and specify a different language for your customers.

To learn more, see Localization: Change the default language.

// Set Custom Language
[Kustomer setLanguage:@"language_code"];

// Example
[Kustomer setLanguage:@"en"];
var options = KustomerOptions()
options.language = .fr
Kustomer.configure(apiKey: "API KEY", options: options, launchOptions: launchOptions)

Customize appearance

To learn more, see Customize Colors.

// The majority of the user interface for the support screens can be configured using UIAppearance. You must call [Kustomer initializeWithAPIKey:kKustomerAPIKey] before changing any appearance values.
  
// Make the navigation bar have a dark gray background
[[KUSNavigationBarView appearance] setBackgroundColor:[UIColor colorWithWhite:0.25 alpha:1.0]];
// Make the navigation bar items orange
[[KUSNavigationBarView appearance] setTintColor:[KUSColor orangeColor]];

// Make the session table view and cells light gray
[[KUSSessionsTableView appearance] setBackgroundColor:[UIColor lightGrayColor]];
[[KUSChatSessionTableViewCell appearance] setBackgroundColor:[UIColor lightGrayColor]];
[[KUSChatSessionTableViewCell appearance] setSelectedBackgroundColor:[UIColor grayColor]];
[[KUSChatPlaceholderTableViewCell appearance] setBackgroundColor:[UIColor lightGrayColor]];

// ...
// The majority of the user interface for the support screens can be configured using an asset catalog. You can also programatically change colors before calling Kustomer.congfigure(...)

// Uses an asset catalog
// See https://developer.kustomer.com/chat-sdk/v2.0.5-iOS/docs/customize-colors

What’s Next