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 MessagingConfigurationlet messagingConfiguration = MessagingConfiguration()messagingConfiguration.name = "My bot name"
// present the messagingViewControllerdo {   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 MessagingConfigurationZDKClassicMessagingConfiguration *messagingConfiguration = [ZDKClassicMessagingConfiguration new];messagingConfiguration.name = @"My bot name";
// present the messagingViewControllerNSError *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 MessagingConfigurationlet messagingConfiguration = MessagingConfiguration()messagingConfiguration.name = "My bot name"
// Construct a RequestUiConfigurationlet requestConfiguration = RequestUiConfiguration()requestConfiguration.tags = ["tag1", "tag2"]requestConfiguration.subject = "Custom subject"

// present the messagingViewControllerdo {   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 MessagingConfigurationZDKClassicMessagingConfiguration *messagingConfiguration = [ZDKClassicMessagingConfiguration new];messagingConfiguration.name = @"My bot name";
// Construct a RequestUiConfurationZDKRequestUiConfiguration *requestConfiguration = [ZDKRequestUiConfiguration new];requestConfiguration.tags = @[@"tag1", @"tag2"];requestConfiguration.subject = @"Custom Subject";
// present the messagingViewControllerNSError *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 enginesguard let answerBotEngine = try? AnswerBotEngine.engine(),		let supportEngine = try? SupportEngine.engine() else {		// do something}
// Construct a HelpCenterUiConfigurationlet helpCenterConfiguration = HelpCenterUiConfiguration()helpCenterConfiguration.engines = [answerBotEngine, supportEngine]helpCenterConfiguration.labels = ["iOS"]
// Construct an ArticleUiConfigurationlet articleConfiguration = ArticleUiConfiguration()articleConfiguration.engines = [answerBotEngine, supportEngine]
// Construct a MessagingConfigurationlet messagingConfiguration = MessagingConfiguration()messagingConfiguration.name = "My bot name"
// Construct a RequestUiConfigurationlet requestConfiguration = RequestUiConfiguration()requestConfiguration.tags = ["tag1", "tag2"]requestConfiguration.subject = "Custom subject"

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

Objective-C

// Construct the enginesNSError *error = nil;ZDKSupportEngine *supportEngine = [ZDKSupportEngine engineAndReturnError:&error];ZDKAnswerBotEngine *answerBotEngine = [ZDKAnswerBotEngine engineAndReturnError:&error];
// Construct a HelpCenterUiConfigurationZDKHelpCenterUiConfiguration * helpCenterConfiguration = [ZDKHelpCenterUiConfiguration new];[helpCenterConfiguration setObjcEngines:@[answerBotEngine, supportEngine]];[helpCenterConfiguration setLabels:@[@"iOS"]];
// Construct an ArticleUiConfigurationZDKArticleUiConfiguration* articleConfiguration = [ZDKArticleUiConfiguration new];[articleConfiguration setObjcEngines:@[answerBotEngine, supportEngine]];
// Construct a MessagingConfigurationZDKClassicMessagingConfiguration *messagingConfiguration = [ZDKClassicMessagingConfiguration new];messagingConfiguration.name = @"My bot name";
// Construct a RequestUiConfurationZDKRequestUiConfiguration *requestConfiguration = [ZDKRequestUiConfiguration new];requestConfiguration.tags = @[@"tag1", @"tag2"];requestConfiguration.subject = @"Custom Subject";
// present the helpCenterViewControllerUIViewController *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 Safarireturn 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)messagingdidPerformEvent:(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.