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 clickedsource
: an enumeration that describes where in the UI theurl
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
- Set the delegate for
Messaging
.
Messaging.delegate = self
- 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
- Set the delegate for
ZDKMessaging
.
ZDKMessaging.delegate = self
- 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.
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. |
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) {
// ...
}];