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//www.ying8.net/are made clickable in the UI. Other URIs such aszendesk://myappwill not be clickable.

You can customize the behavior and change what happens when the user clicks a URL by setting aMessagingDelegate. TheshouldHandleUrlfunction 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
• urlSource: an enumeration that describes where in the UI theurlwas clicked, such as a text message, a carousel item, and so on.

The following snippets show how you can set aMessagingDelegatein 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 customreturn false}})
             

Java

             

              
Messaging.setDelegate(newMessagingDelegate(){@Overridepublic booleanshouldHandleUrl(@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 customreturnfalse;}});
             

Events

The Zendesk SDK for Android provides an event listenerZendeskEventListenerwhere you can listen for anyZendeskEventemitted from the SDK.

Available Events

ZendeskEventis a sealed class with a subclass for each event that can currently be emitted. It has the following events:

• UnreadMessageCountChanged
• AuthenticationFailed

UnreadMessageCountChanged

The number of unread messages has changed.

AuthenticationFailed

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

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 theZendeskEventListenerAdapter, an implementation of theZendeskEventListenerdesigned to provide better support for Java:

             

              
// To create and use the event listener:ZendeskEventListener zendeskEventListener=newZendeskEventListener(){@Overridepublic voidonEvent(@NonNull ZendeskEvent zendeskEvent){if(zendeskEventinstanceofUnreadMessageCountChanged){// Your custom action...}elseif(zendeskEventinstanceofAuthenticationFailed){// Your custom action...}}};// Or using the ZendeskEventListenerAdapter:亚博ZendeskEventListenerAdapter listenerAdapter=newZendeskEventListenerAdapter(){@Overridepublic voidonUnreadMessageCountChanged(@NonNull UnreadMessageCountChanged event){super.onUnreadMessageCountChanged(event);// Your custom action}};// To add the event listener to your Zendesk instance:亚博.addEventListener(zendeskEventListener);// To remove the event listener from your Zendesk instance:亚博.removeEventListener(zendeskEventListener);
             

EventFlow

下面的代码示例显示了使用thezendesk.eventFlowAPI:

             

              
lifecycleScope.launch {zendesk.eventFlow.collect { zendeskEvent ->when (zendeskEvent) {is ZendeskEvent.UnreadMessageCountChanged -> // Your custom actionelse -> 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 ishere. The steps mentioned in this article should be completed before beginning the steps below.

LoginUser

To authenticate a user call theloginUserAPI with your ownJWT.

TheJWTcan contain the following fields:

Kotlin

             

              
Zendesk.instance.loginUser(jwt = "your_jwt_here",successCallback = { user -> },failureCallback = { error -> })
             

Java

             

              
亚博.getInstance().loginUser("your_jwt_here",newSuccessCallback<ZendeskUser>(){@Overridepublic voidonSuccess(ZendeskUser value){}},newFailureCallback<Throwable>(){@Overridepublic voidonFailure(@NonNull Throwable error){}});
             

LogoutUser

To unauthenticate a user call thelogoutUserAPI.

This is primarily for authenticated users but callinglogoutUserfor 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

             

              
亚博.getInstance().logoutUser(newSuccessCallback<Unit>(){@Overridepublic voidonSuccess(Unit value){}},newFailureCallback<Throwable>(){@Overridepublic voidonFailure(@NonNull Throwable error){}});
             

Authentication Errors

All authentication errors can be observed throughEvents.

The most common error that will happen here is a HTTP 401 error. In this case a newJWTshould be generated and a call made tologinUser.

访客路径

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

Page View Event

ThePageViewobject 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 aPageViewobject as a parameter. Pass the location of the screen that the end user is on tourland the name of the screen topageTitle.

             

              
// Create a `PageView` objectval pageView = PageView(url = url, pageTitle = pageTitle)Zendesk.instance.sendPageView(pageView,successCallback = { user -> },failureCallback = { error -> })
             

Java

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

The API accepts aPageViewobject as a parameter. Pass the location of the screen that the end user is on tourland the name of the screen topageTitle.

             

              
PageView pageView=newPageView(url,pageTitle);亚博.getInstance().sendPageViewEvent(pageView,newSuccessCallback<Unit>(){@Overridepublic voidonSuccess(Unit value){}},newFailureCallback<Throwable>(){@Overridepublic voidonFailure(@NonNull Throwable error){}});
             

Proactive messaging

Proactive messaging can deliver targeted local push notifications to your users through your mobile SDK channel when triggering pre-defined conditions. SeeCreating proactive messages for mobile SDK channelsfor 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 Android local notifications to deliver messages to users that meet your pre-defined conditions.

Zendesk SDK for Android will request notification permissions from the user only when they open the conversation screen (if they haven't been prompted previously) so a proactive message can be displayed.

Make sure your project requests notification permissions from the user before they open the conversation screen, if you want Proactive messages to display before this.

Relationship with the Page View event

A proactive messaging campaign is evaluated when triggered by thePage 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.

Kotlin

             

              
val colors = UserColors(onPrimary = Color.Black,onMessage = Color.Black,onAction = Color.Black)val factory = DefaultMessagingFactory(userLightColors = colors,userDarkColors = colors)Zendesk.initialize(context = this,channelKey = "channel_key",messagingFactory = factory,)
             

Java

             

              
UserColors colors=newUserColors(Color.BLACK,Color.BLACK,Color.BLACK);DefaultMessagingFactory factory=newDefaultMessagingFactory(colors,colors);亚博.initialize(this,"channel_key",factory);