Advanced integration

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

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.

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` objectlet 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 PageViewZDKPageView *pageView = [[ZDKPageView alloc] initWithPageTitle:@"page title" url:@"www.example.com"];[zendesk sendPageViewEvent:pageView completionHandler:^(NSError *error) {    if (error != nil) {        // handle error    }}];