Configuring the SDK

Configuring the SDK

The Zendesk mobile SDKs provide default out-of-the-box behavior for many features that can be customized in code.

Using SDK configurations

Each of the SDK ViewController classes has a corresponding class implementation of the Configuration protocol.

Each Configuration class has a selection of properties you can set to configure the appearance or behavior of the ViewController.

You pass a Configuration to a SDK buildUI method, which returns an instance of a UIViewController to be shown on screen.

Customizing the bot label string

You can customize the string used for the "Answer Bot" label in the Unified SDK. This bot label is used across all the product SDK's engines (Answer Bot, Chat, and Support). The bordered "Bot" label that follows your bot label can't be removed.

Here's a simple example that customizes the string used for the "Answer Bot" label in the Unified SDK.

Swift

// Construct a MessagingConfiguration
let messagingConfiguration = MessagingConfiguration()
messagingConfiguration.name = "My bot name"

// present the messagingViewController
do {
   let answerBotEngine = try AnswerBotEngine.engine()
   let viewController = try Messaging.instance.buildUI(engines: [answerBotEngine],
        configs: [messagingConfiguration])
   self.navigationController?.pushViewController(viewController, animated: true)
} catch {
   // do something with error
}

Objective-C

// Construct a MessagingConfiguration
ZDKClassicMessagingConfiguration *messagingConfiguration = [ZDKClassicMessagingConfiguration new];
messagingConfiguration.name = @"My bot name";

// present the messagingViewController
NSError *error = nil;
ZDKAnswerBotEngine *answerBotEngine = [ZDKAnswerBotEngine engineAndReturnError:&error];
UIViewController *viewController = [[ZDKClassicMessaging instance] buildUIWithEngines: @[(id<ZDKEngine>)answerBotEngine]
                                                                       configs: @[messagingConfiguration]
                                                                         error: &error];
[self.navigationController pushViewController:viewController animated:YES];

Note: While Answer Bot is a specific Zendesk product, the string "Answer Bot" is used by default for all automated messages shown in the Unified SDK even if the active engine is not Answer Bot (for example, the Support engine displays automated messages prompting the user for an email address, or confirming when a ticket has been created). This is the case regardless of whether you have an active subscription to the Answer Bot product or not.

Multiple configurations in one screen

Each buildUI method takes an array of Configuration configurations. Use this feature to configure multiple screens or features at once. The following example shows how to customize the "Answer Bot" label string as well as set a custom subject and tags for any requests created by the Support engine:

Swift

// Construct a MessagingConfiguration
let messagingConfiguration = MessagingConfiguration()
messagingConfiguration.name = "My bot name"

// Construct a RequestUiConfiguration
let requestConfiguration = RequestUiConfiguration()
requestConfiguration.tags = ["tag1", "tag2"]
requestConfiguration.subject = "Custom subject"


// present the messagingViewController
do {
   let answerBotEngine = try AnswerBotEngine.engine()
   let viewController = try Messaging.instance.buildUI(engines: [answerBotEngine],
    											configs: [messagingConfiguration, requestConfiguration])
   self.navigationController?.pushViewController(viewController, animated: true)
} catch {
   // do something with error
}

Objective-C

// Construct a MessagingConfiguration
ZDKClassicMessagingConfiguration *messagingConfiguration = [ZDKClassicMessagingConfiguration new];
messagingConfiguration.name = @"My bot name";

// Construct a RequestUiConfuration
ZDKRequestUiConfiguration *requestConfiguration = [ZDKRequestUiConfiguration new];
requestConfiguration.tags = @[@"tag1", @"tag2"];
requestConfiguration.subject = @"Custom Subject";

// present the messagingViewController
NSError *error = nil;
ZDKSupportEngine *supportEngine = [ZDKSupportEngine engineAndReturnError:&error];
UIViewController *messagingViewController = [[ZDKClassicMessaging instance]
    				buildUIWithEngines:@[supportEngine]
    				configs:@[messagingConfiguration, requestConfiguration]
    				error:&error];

For more details, see Running the Answer Bot engine and Running the Support engine. For the Chat engine, please refer directly to Chat SDK v2 - Getting Started.
For information about MessagingActivity, see What does the flow of MessagingActivity look like with multiple Engines.

Multiple configurations for multiple screens

You can also use the following pattern to configure more than one SDK UIViewController at once. For example, when using the Support SDK, you can configure the Help Center screen and the Article screen to open the Messaging screen with the Answer Bot and Support engines. Here's how to configure all of these at once:

Swift

// Construct the engines
guard let answerBotEngine = try? AnswerBotEngine.engine(),
		let supportEngine = try? SupportEngine.engine() else {
		// do something
}

// Construct a HelpCenterUiConfiguration
let helpCenterConfiguration = HelpCenterUiConfiguration()
helpCenterConfiguration.engines = [answerBotEngine, supportEngine]
helpCenterConfiguration.labels = ["iOS"]

// Construct an ArticleUiConfiguration
let articleConfiguration = ArticleUiConfiguration()
articleConfiguration.engines = [answerBotEngine, supportEngine]

// Construct a MessagingConfiguration
let messagingConfiguration = MessagingConfiguration()
messagingConfiguration.name = "My bot name"

// Construct a RequestUiConfiguration
let requestConfiguration = RequestUiConfiguration()
requestConfiguration.tags = ["tag1", "tag2"]
requestConfiguration.subject = "Custom subject"


// present the helpCenterViewController
let helpCenter = HelpCenterUi.buildHelpCenterOverviewUi(withConfigs: [helpCenterConfiguration, articleConfiguration, messagingConfiguration, requestConfiguration])
self.navigationController?.pushViewController(helpCenter, animated: true)

Objective-C

// Construct the engines
NSError *error = nil;
ZDKSupportEngine *supportEngine = [ZDKSupportEngine engineAndReturnError:&error];
ZDKAnswerBotEngine *answerBotEngine = [ZDKAnswerBotEngine engineAndReturnError:&error];

// Construct a HelpCenterUiConfiguration
ZDKHelpCenterUiConfiguration * helpCenterConfiguration = [ZDKHelpCenterUiConfiguration new];
[helpCenterConfiguration setObjcEngines:@[answerBotEngine, supportEngine]];
[helpCenterConfiguration setLabels:@[@"iOS"]];

// Construct an ArticleUiConfiguration
ZDKArticleUiConfiguration* articleConfiguration = [ZDKArticleUiConfiguration new];
[articleConfiguration setObjcEngines:@[answerBotEngine, supportEngine]];

// Construct a MessagingConfiguration
ZDKClassicMessagingConfiguration *messagingConfiguration = [ZDKClassicMessagingConfiguration new];
messagingConfiguration.name = @"My bot name";

// Construct a RequestUiConfuration
ZDKRequestUiConfiguration *requestConfiguration = [ZDKRequestUiConfiguration new];
requestConfiguration.tags = @[@"tag1", @"tag2"];
requestConfiguration.subject = @"Custom Subject";

// present the helpCenterViewController
UIViewController *helpCenter = [ZDKHelpCenterUi buildHelpCenterOverviewUiWithConfigs:@[helpCenterConfiguration, articleConfiguration, messagingConfiguration, requestConfiguration]];
[self.navigationController pushViewController:helpCenter animated:YES];

Custom URL handling

You can customize the behavior of the Unified SDK in relation to URL handling by implementing the messagingShouldOpenURL delegate method as shown in the following code examples.

Swift

1. Set the delegate for Messaging.

   Messaging.instance.delegate = self

2. Handle the URL in the delegate method func messaging(_ messaging: Messaging, shouldOpenURL url: URL) -> Bool.

   func messaging(_ messaging: Messaging, shouldOpenURL url: URL) -> Bool {
      // By default the links shared in the conversation are opened in Safari
      true
   }

Objective-C

1. Set the delegate for Messaging.

   [ZDKClassicMessaging instance].delegate = self;

2. Handle the URL in the delegate method - (BOOL)messaging:(ZDKClassicMessaging *)messaging shouldOpenURL:(NSURL *)url.

   - (BOOL)messaging:(ZDKClassicMessaging *)messaging shouldOpenURL:(NSURL *)url {
   // By default the links shared in the conversation are opened in Safari
   return YES;
   }

Observe the UI lifecycle events

You can observe the UI lifecycle events by following the steps in the examples below. A complete list of possible events is displayed following the examples.

Swift

1. Set the delegate for Messaging.

   Messaging.instance.delegate = self

2. Handle the events in the delegate method func messaging(_ messaging: Messaging, didPerformEvent event: MessagingUIEvent, context: Any?).

   extension ZendeskChat: MessagingDelegate {
      func messaging(_ messaging: Messaging, didPerformEvent event: MessagingUIEvent, context: Any?) {
         switch event {
            case .viewDidLoad:
               break
            @unknown default:
               break
         }
      }
   }

Objective-C

1. Set the delegate for Messaging.

   [ZDKClassicMessaging instance].delegate = self

2. Handle the events in the delegate method - (void)messaging:(ZDKClassicMessaging * _Nonnull)messaging didPerformEvent:(enum ZDKClassicMessagingUIEvent)event context:(id _Nullable)context.

   - (void)messaging:(ZDKClassicMessaging * _Nonnull)messaging
   didPerformEvent:(enum ZDKClassicMessagingUIEvent)event
            context:(id _Nullable)context {
      switch (event) {
         case ZDKClassicMessagingUIEventViewDidLoad:
               break;
         default:
               break;
      }
   }

The following table lists all the lifecycle events that can be observed.

Event	Description
.viewDidLoad	The view has loaded
.viewWillAppear	The view will appear
.viewDidAppear	The view did appear
.viewWillDisappear	The view will disappear
.viewDidDisappear	The view did disappear
.viewDidLayoutSubviews	The view has laid out subviews
.viewControllerDidClose	The messaging view controller has closed