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:
- the default browser for a URL
- the default phone app for a phone number
- the 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 shouldHandleUrl
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 clickedurlSource
: an enumeration that describes where in the UI theurl
was clicked, such as a text message, a carousel item, and so on.
The following snippets show how you can set a MessagingDelegate
in Kotlin and Java:
Kotlin
Messaging.setDelegate(object : MessagingDelegate() {
override fun shouldHandleUrl(url: String, urlSource: UrlSource): Boolean {
// 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 false
}
})
Java
Messaging.setDelegate(new MessagingDelegate() {
@Override
public boolean shouldHandleUrl(@NotNull String url, @NotNull UrlSource urlSource) {
// 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 false;
}
});
Events
The Zendesk SDK for Android provides an event listener ZendeskEventListener
where you can listen for any ZendeskEvent
emitted from the SDK.
Available Events
ZendeskEvent
is a sealed class with a subclass for each event that can currently be emitted. It has the following events:
UnreadMessageCountChanged
The number of unread messages has changed.
Name | Type | Comment |
---|---|---|
currentUnreadCount | Int | The current 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. |
EventListener
Kotlin
Here is a code sample showing how the the event listener can be used, added and removed:
// To create and use the event listener:
val zendeskEventListener: ZendeskEventListener = ZendeskEventListener {
zendeskEvent -> when (zendeskEvent) {
is ZendeskEvent.UnreadMessageCountChanged ->{
// Your custom action...
}
is ZendeskEvent.AuthenticationFailed -> {
// Your custom action...
}
else -> {
// Default branch for forward compatibility with Zendesk SDK and its `ZendeskEvent` expansion
}
}
}
// To add the event listener to your Zendesk instance:
// (safe for concurrent use)
zendesk.addEventListener(zendeskEventListener)
// To remove the event listener from your Zendesk instance:
// (safe for concurrent use)
zendesk.removeEventListener(zendeskEventListener)
Java
Below is a code sample showing how the the event listener can be used, added and removed.
This includes the ZendeskEventListenerAdapter
, an implementation of the ZendeskEventListener
designed to provide better support for Java:
// To create and use the event listener:
ZendeskEventListener zendeskEventListener =
new ZendeskEventListener() {
@Override
public void onEvent(@NonNull ZendeskEvent zendeskEvent) {
if (zendeskEvent instanceof UnreadMessageCountChanged) {
// Your custom action...
} else if (zendeskEvent instanceof AuthenticationFailed){
// Your custom action...
}
}
};
// Or using the ZendeskEventListenerAdapter:
ZendeskEventListenerAdapter listenerAdapter = new ZendeskEventListenerAdapter() {
@Override
public void onUnreadMessageCountChanged(@NonNull UnreadMessageCountChanged event) {
super.onUnreadMessageCountChanged(event);
// Your custom action
}
};
// To add the event listener to your Zendesk instance:
zendesk.addEventListener(zendeskEventListener);
// To remove the event listener from your Zendesk instance:
zendesk.removeEventListener(zendeskEventListener);
EventFlow
Below is a code sample which shows the usage of the zendesk.eventFlow
API:
lifecycleScope.launch {
zendesk.eventFlow.collect { zendeskEvent ->
when (zendeskEvent) {
is ZendeskEvent.UnreadMessageCountChanged -> // Your custom action
else -> Unit
}
}
}
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. |
String | The email of the user. Optional. |
Kotlin
Zendesk.instance.loginUser(jwt = "your_jwt_here",
successCallback = { user -> },
failureCallback = { error -> }
)
Java
Zendesk.getInstance().loginUser("your_jwt_here", new SuccessCallback<ZendeskUser>() {
@Override
public void onSuccess(ZendeskUser value) {
}
}, new FailureCallback<Throwable>() {
@Override
public void onFailure(@NonNull Throwable 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.
Kotlin
Zendesk.instance.logoutUser(
successCallback = { },
failureCallback = { error -> }
)
Java
Zendesk.getInstance().logoutUser(new SuccessCallback<Unit>() {
@Override
public void onSuccess(Unit value) {
}
}, new FailureCallback<Throwable>() {
@Override
public void onFailure(@NonNull Throwable 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.
Kotlin
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
val pageView = PageView(url = url, pageTitle = pageTitle)
Zendesk.instance.sendPageViewEvent(pageView) {
// Your custom result handling...
}, { error ->
// Your error handling
},
Java
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
.
PageView pageView = new PageView(url, pageTitle);
Zendesk.getInstance().sendPageViewEvent(pageView, new SuccessCallback<Unit>() {
@Override
public void onSuccess(Unit value) {
}
}, new FailureCallback<Throwable>() {
@Override
public void onFailure(@NonNull Throwable error) {
}
});