Advanced integration

Advanced integration

Clickable links delegate

When a user taps a URL, phone number, or email address sent to a conversation, the SDK handles the event automatically by launching the default app capable of completing the action:

• default browser for a URL
• default phone app for a phone number
• default email app for an email address

Note: Only URLs such as https://www.zendesk.com/ are made clickable in the UI. Other URIs such as zendesk://myapp will not be clickable.

You can customize the behavior and change what happens when the user clicks a URL by setting a MessagingDelegate. The messaging(:shouldHandleURL:from:) function will be called any time the user clicks a URL.

To prevent the SDK from opening the default browser, you should return false when this happens. In that case, you must handle the completion of the action yourself. The function receives two parameters:

• url: the URL that was clicked
• source: an enumeration that describes where in the UI the url was clicked, such as a text message, a carousel item, and so on.

The snippets below show how you can set a MessagingDelegate in Swift and Objective-C:

Swift

1. Set the delegate for Messaging.

Messaging.delegate = self

1. Handle the URL in the delegate method messaging(_ messaging: Messaging, shouldHandleURL url: URL, from source: URLSource) -> Bool.

func messaging(_ messaging: Messaging, shouldHandleURL url: URL, from source: URLSource) -> Bool {
    // Your custom action...

    // Return false to prevent the SDK from handling the URL automatically
    // Return true to allow the SDK to handle the URL automatically, even
    // if you have done something custom
    false
}

Objective-C

1. Set the delegate for ZDKMessaging.

ZDKMessaging.delegate = self

1. Handle the URL in the delegate method - (BOOL)messaging:(ZDKMessaging * _Nonnull)messaging shouldHandleURL:(NSURL * _Nonnull)URL from:(enum ZDKURLSource)source.

- (BOOL)messaging:(ZDKMessaging * _Nonnull)messaging shouldHandleURL:(NSURL * _Nonnull)URL from:(enum ZDKURLSource)source {
    // Your custom action...

    // Return false to prevent the SDK from handling the URL automatically
    // Return true to allow the SDK to handle the URL automatically, even
    // if you have done something custom
    return NO;
}

Events

The Zendesk SDK for iOS provides an event observer where you can listen for any ZendeskEvent emitted from the SDK.

Available Events

ZendeskEvent is a non-frozen enum with a case for each event that can currently be emitted. It has the following cases:

• unreadMessageCountChanged
• authenticationFailed

unreadMessageCountChanged

Invoked when there is a change to the current total number of unread messages.

Name	Type	Comment
currentUnreadCount	Int	The current total number of unread messages.

authenticationFailed

Invoked when an authentication error has occurred on any of the API calls.

Name	Type	Comment
error	Error	Details about the error that occurred.

EventObserver

Swift

Below is a code sample showing how the event observer can be added and removed.

There is currently only one case to match against, but since the enum is non-frozen, additional cases may be added in the future.

For this reason, add a "catch-all" case @unknown default that matches any value and produces a warning if all known elements of the enum have not already been matched. If additional cases are added and you do not wish to see a warning here, remove the @unknown attribute. See the snippet below:

// To add an event observer to your Zendesk instance:
Zendesk.instance?.addEventObserver(self) { event in
    switch event {
    case .unreadMessageCountChanged(let unreadCount):
        // Your custom action...
    case .authenticationFailed(let error as NSError):
        print("Authentication error received: \(error)")
        print("Domain: \(error.domain)")
        print("Error code: \(error.code)")
        print("Localized Description: \(error.localizedDescription)")
        // ...
    @unknown default:
        break
    }
}

// To remove an event observer from your Zendesk instance:
Zendesk.instance?.removeEventObserver(self)

Objective-C

Below is a code sample showing how the event observer can be added and removed.

Each case in ZDKZendeskEvent is prefixed with ZDKZendeskEvent in the following format:

ZDKZendeskEvent{EventName}

There is currently only one case to match against, but since the enum is non-frozen, there may be additional cases added in the future. For this reason, add a "catch-all" case default that matches any value.

// Get your Zendesk instance:
Zendesk *instance = [Zendesk instance];

// To add an event observer to your Zendesk instance:
[instance addEventObserver:self :^(enum ZDKZendeskEvent event, id _Nullable value) {
    switch (event) {
    case ZDKZendeskEventUnreadMessageCountChanged:
        // Your custom action...
    case ZDKZendeskEventAuthenticationFailed: 
        // Your custom action...
    default:
        break;
    }
}];

// To remove an event observer from your Zendesk instance:
[instance removeEventObserver:self];

Authentication

The Zendesk SDK allows authentication of end users so that their identity can be verified by agents using Zendesk. A detailed article on the steps to set up authentication for your account is here. The steps mentioned in this article should be completed before beginning the steps below.

You can find a demo app demonstrating the capability of user authentication on our Demo app repository.

LoginUser

To authenticate a user call the loginUser API with your own JWT.

The JWT can contain the following fields:

Name	Type	Comment
external_id	String	The external id of the user. Required.
name	String	The name of the user. Optional.
email	String	The email of the user. Optional.

Swift

The result of loginUser can be observed in the optional completionHandler.

Zendesk.instance?.loginUser(with: "your_jwt_here") { result in
    switch result {
    case .success(let user):
        // ...
    case .failure(let error):
        // ...
    }         
}

Objective-C

Zendesk *instance = [Zendesk instance];

[instance loginUserWith:@"your_jwt_here" completionHandler:^(ZDKZendeskUser * _Nullable user, NSError * _Nullable error) {
    // ...
}];

LogoutUser

To unauthenticate a user call the logoutUser API.

This is primarily for authenticated users but calling logoutUser for an unauthenticated user will clear all of their data, including their conversation history. Please note that there is no way for us to recover this data, so only use this for testing purposes. The next time the unauthenticated user enters the conversation screen a new user and conversation will be created for them.

Swift

The result of logoutUser can be observed in the optional completionHandler.

Zendesk.instance?.logoutUser { result in
    switch result {
    case .success:
        // ...
    case .failure(let error):
        // ...
    }
}

Objective-C

Zendesk *instance = [Zendesk instance];

[instance logoutUserWithCompletionHandler:^(NSError * _Nullable error) {
  // ...
}];

Authentication Errors

All authentication errors can be observed through Events.

The most common error that will happen here is a HTTP 401 error. In this case a new JWT should be generated and a call made to loginUser.

Visitor Path

The Visitor Path lets agents see what screen the end user had landed on, for better conversation context.

Page View Event

The PageView object encapsulates information related to a user’s interactions and passes it to the Page View Event API. These session-based page view events can be seen in Agent Workspace by support agents using Zendesk.

Swift

Below is a code sample showing how to send a Page View Event.

The API accepts a PageView object as a parameter. Pass the location of the screen that the end user is on to url and the name of the screen to pageTitle.

// Create a `PageView` object
let pageView = PageView(pageTitle: pageTitle, url: url)
Zendesk.instance?.sendPageViewEvent(pageView) { result in
    // Your custom result handling...
}

Objective-C

Below is a code sample showing how to send a Page View Event.

The API accepts a PageView object as a parameter. Pass the location of the screen that the end user is on to url and the name of the screen to pageTitle.

// Get your Zendesk instance:
Zendesk *instance = [Zendesk instance];
// Create a PageView
ZDKPageView *pageView = [[ZDKPageView alloc] initWithPageTitle:@"page title" url:@"www.example.com"];
[zendesk sendPageViewEvent:pageView completionHandler:^(NSError *error) {
    if (error != nil) {
        // handle error
    }
}];

Proactive messaging

Proactive messaging can deliver targeted local push notifications to your users through your mobile SDK channel when triggering pre-defined conditions. See Creating proactive messages for mobile SDK channels for information on creating a proactive messaging campaign for your channel. The steps mentioned in the article should be completed before performing the steps below.

Local push notifications

Proactive messaging uses iOS local notifications to deliver messages to users that meet your pre-defined conditions.

The ZendeskSDK will request notification permission from the user (if they haven't been prompted previously) so a proactive message can be displayed.

Follow the steps in implementing push notifications in your app's codebase to ensure your project can handle the push notifications actions correctly. You must implement the handleTap function inside userNotificationCenter(didReceive) to display the conversation view after the end user taps on the proactive Message notification.

Swift

PushNotifications.handleTap(userInfo) { viewController in
    // Handle displaying the returned viewController in here
}

Objective-C

[ZDKPushNotifications handleTap:userInfo completion:^(UIViewController * _Nullable viewController) {
    // Handle displaying the returned viewController in here
}];

Relationship with the Page View event

A proactive messaging campaign is evaluated when triggered by the Page View Event integration. It is essential that for each screen the user visits, the page view event is correctly updated to reflect this.

For example, suppose you have a campaign that triggers when the user is on a particular product screen for 30 seconds. If the user navigates to a different screen after 25 seconds, and there's no subsequent page view event sent, the user will receive a proactive message notification.

Customization

The style of the Zendesk SDK can be set through Admin Center which currently includes the primary color, the message color and the action color.

There is additional customization support available for setting text colors through the SDK using the following API. Please note this is a temporary API which will be available until the same feature is supported in Admin Center. This API will then be deprecated.

When initializing the Zendesk SDK, different text colors can now be passed as parameters to compliment the available style colors, with support for both light and dark mode.

Swift

let colors = UserColors(onPrimary: .black, 
                        onMessage: .black, 
                        onAction: .black)
let factory = DefaultMessagingFactory(userLightColors: colors, 
                                      userDarkColors: colors)
Zendesk.initialize(withChannelKey: "channel_key",  
                   messagingFactory: factory) { result in
    // ...
}

Objective-C

ZDKUserColors *colors = [[ZDKUserColors alloc] initOnPrimary:UIColor.blackColor
                                                   onMessage:UIColor.blackColor
                                                    onAction:UIColor.blackColor];
ZDKDefaultMessagingFactory *factory = [[ZDKDefaultMessagingFactory alloc] initWithUserLightColors:colors
                                                                                   userDarkColors:colors];
[Zendesk initializeWithChannelKey:@"channel_key"
                 messagingFactory:factory
                completionHandler:^(Zendesk * _Nullable zendesk, NSError * _Nullable error) {
    // ...
}];

Messaging Metadata

To learn more about Messaging Metadata, see Introduction to Messaging Metadata.

Note: The SDK must be initialized before using any of these methods. See Initialize the SDK for more details.

Conversation Fields

Set Conversation Fields

Allows values for conversation fields to be set in the SDK to add contextual data about the conversation.

Zendesk.instance.messaging.setConversationFields(_ fields: [String : AnyHashable])

Conversation fields must first be created as custom ticket fields and configured to allow their values to be set by end users in Admin Center. To use conversation fields, see Using Messaging Metadata with the Zendesk Web Widgets and SDKs.

The values stored are persisted, and will be applied to all conversations going forward. To remove conversation fields stored in the SDK, use the clearConversationFields API.

Note: Conversation fields are not immediately associated with a conversation when the API is called. Calling the API will store the conversation fields, but those fields will only be applied to a conversation when end users either start a new conversation or send a new message in an existing conversation.

Note: An event for handling failed validation checks on conversation fields set using the setConversationFields API will be added in an upcoming release of the Zendesk SDK.

System ticket fields, such as the Priority field, are not supported.

Parameters

fields: [String : AnyHashable]: Is a dictionary of key-value pairs.

Type	Description
String	id of custom ticket field
AnyHashable	value of the custom ticket field

Note: The supported types for AnyHashable are string, number and boolean.

Example

For example, if the id of your custom text field for a flight number is 4422761977114 and you want to set its value to FA2590, then you would call:

Swift

Zendesk.instance.messaging.setConversationFields(["4422761977114": "FA2590"])

Objective-C

[Zendesk.instance.messaging setConversationFields:@{@"4422761977114": @"FA2590"}];

Clear Conversation Fields

You can clear conversation fields from the SDK storage when the client side context changes. To do this, use the clearConversationFields API. This removes all stored conversation fields from the SDK storage.

Note: This API does not affect conversation fields already applied to the conversation.

Example

Swift

Zendesk.instance.messaging.clearConversationFields()

Objective-C

[Zendesk.instance.messaging clearConversationFields];

Conversation Tags

Set Conversation Tags

Allows custom conversation tags to be set in the SDK to add contextual data about the conversation.

Zendesk.instance.messaging.setConversationTags(_ tags: [String])

To use conversation tags, refer to Using Messaging Metadata with the Zendesk Web Widgets and SDKs.

Note: Conversation tags are not immediately associated with a conversation when the API is called. It will only be applied to a conversation when end users either start a new conversation or send a new message in an existing conversation.

Parameters

[String] An array of strings.

Type	Description
[String]	The array of custom tags to be provided.

Example

For example, to apply promo_code and discount tags to a conversation about an order, then you would call:

Swift

Zendesk.instance.messaging.setConversationTags(["promo_code", "discount"])

Objective-C

[Zendesk.instance.messaging setConversationTags:@[@"promo_code", @"discount"]];

Clear Conversation Tags

Allows you to clear conversation tags from SDK storage when the client side context changes. To do this, use the clearConversationTags API. This removes all stored conversation tags from the SDK storage.

Note: This API does not affect conversation tags already applied to the conversation.

Example

Swift

Zendesk.instance.messaging.clearConversationTags()

Objective-C

[Zendesk.instance.messaging clearConversationTags];