LiveChat for Android
An Android SDK for integrating LiveChat functionality into your mobile application.
Getting started
Add real-time customer support to your Android application with LiveChat's native SDK. This guide covers installation, basic setup, and advanced features.
💡 The SDK is now Kotlin-based and uses the new package com.livechatinc.chatsdk
. See migration notes if you are upgrading from v2.x.x.
Requirements
The Android SDK is compatible with:
- Android 5.0 (API level 21) or higher
- Java 8 or higher
Installation
To install the SDK, first add the JitPack repository to your root build.gradle
:
ADD JITPACK REPOSITORY
allprojects {
repositories {
maven { url 'https://jitpack.io' }
}
}
Next, add dependency to your app's build.gradle
:
ADD DEPENDENCY
dependencies {
implementation 'com.github.livechat:chat-window-android:3.0.0'
}
Then, add Internet permission to AndroidManifest.xml
:
ADD PERMISSION
<uses-permission android:name="android.permission.INTERNET" />
Initialization
You can initialize the SDK in the onCreate()
method of your Application
instance:
INITIALIZE
LiveChat.initialize("<LICENSE>", this)
Display the chat window
The function below allows you to display a chat to a customer:
SHOW CHAT
LiveChat.getInstance().show()
That's it! Your customers can start chatting with you now.
Customer information
You can pre-fill the pre-chat form fields with customer information to provide your agents with more details about the customer. All information is optional.
The group ID defaults to 0
if not provided.
CUSTOMER INFO - KOTLIN
LiveChat.getInstance().setCustomerInfo(
"Joe", // Name
"joe@mail.com", // Email
"0", // Group ID, defaults to "0"
Collections.singletonMap("internalCustomerId", "ABC123") // Custom params
)
CUSTOMER INFO - JAVA
Map<String, String> customParams = new HashMap<>();
customParams.put("internalCustomerId", "ABC123");
LiveChat.getInstance().setCustomerInfo(
"Joe", // Name
"joe@mail.com", // Email
"0", // Group ID
customParams // Custom params
);
Note: You should call the setCustomerInfo()
before LiveChat.getInstance().show()
. To update customer properties when the chat has already loaded, recreate it with LiveChat.getInstance().destroyLiveChatView()
and LiveChat.getInstance().getLiveChatView()
.
Unread message counter
To get notified about new messages in the chat, use com.livechatinc.chatsdk.src.domain.listeners.NewMessageListener
.
Set it wherever you want to react to a new message, for example, to increase the badge count.
NEW MESSAGES - KOTLIN
LiveChat.getInstance().newMessageListener =
NewMessageListener { message, isChatShown ->
// Handle new message
}
NEW MESSAGES - JAVA
LiveChat.getInstance().setNewMessageListener((chatMessage, isChatShown) -> {
// Handle new message
});
UI customization
While the chat appearance and language are managed through the application settings, you can customize the error view when the chat cannot be loaded.
Error view
You can localize and change the text displayed in the error view by overriding string resources in your app's strings.xml
. All strings can be found in the GitHub repository.
You can also entirely override the default error view by including live_chat_error_layout.xml
in your app's layout resources.
Note: Your custom error view must contain a View
with live_chat_error_button
id when using LiveChat.getInstance().show()
.
Activity
By default, activity will follow your activity's theme. To change this configuration, you can override the activity declaration in your app's AndroidManifest.xml
file.
Clearing chat session
The chat window uses WebView's cookies to store the session. To clear the chat session, call:
CLEAR CHAT SESSION
LiveChat.getInstance().signOutCustomer()
Link handling
By default, links in the chat are opened in the customer's default browser. If you want to intercept the link and handle it in your app, provide your UrlHandler
.
HANDLE LINKS - KOTLIN
LiveChat.getInstance().urlHandler =
UrlHandler { url ->
// Return true if handled, false to open in browser
return@UrlHandler false
}
HANDLE LINKS - JAVA
LiveChat.getInstance().setUrlHandler(uri -> {
// Return true if handled, false to open in browser
return false;
});
Troubleshooting
Error handling
You can set an error listener to monitor and handle issues related to loading the chat view. This allows you to capture and respond to errors in a centralized way. Common use cases include reporting errors to analytics platforms or implementing custom error-handling logic.
ERRORS - KOTLIN
LiveChat.getInstance().errorListener = ErrorListener { error ->
// Handle the error
}
ERRORS - JAVA
LiveChat.getInstance().setErrorListener((error) -> {});
Logger
You can configure the logging level to help with debugging and troubleshooting. Set the desired level before initializing LiveChat:
LOGGER - KOTLIN
Logger.setLogLevel(Logger.LogLevel.VERBOSE)
LOGGER - JAVA
Logger.setLogLevel(Logger.LogLevel.VERBOSE);
Refer to the Logger for all available log levels.
Note: Network calls require at least the INFO
level. DEBUG
and VERBOSE
levels are more detailed.
Missing file picker activity
If you want to react or track instances where the activity for file picking on the user device is not found, you can set a listener for this event:
FILE PICKER NOT FOUND - KOTLIN
LiveChat.getInstance().filePickerNotFoundListener = FilePickerActivityNotFoundListener {
// Handle file picker activity not found
}
FILE PICKER NOT FOUND - JAVA
LiveChat.getInstance().setFilePickerNotFoundListener(() -> {});
Advanced usage
The following features give you more control over the SDK integration. Note that they require additional implementation steps. If you decide to use any of these, please let us know about your use case — we would love to hear about it!
LiveChatView lifecycle scope
By default, after the LiveChat.getInstance().show()
view is initialized, it's kept in the application memory. This allows you to react to new messages, for example, display a counter for unread messages. To automatically free up memory when the chat is no longer visible, you can use LiveChatViewLifecycleScope
to control its lifecycle.
You should specify the scope when initializing the SDK:
LIFECYCLE SCOPE - KOTLIN
LiveChat.initialize("<LICENSE>", this, lifecycleScope = LiveChatViewLifecycleScope.ACTIVITY)
LIFECYCLE SCOPE - JAVA
LiveChat.initialize("<LICENSE>", this, LiveChatViewLifecycleScope.ACTIVITY);
Note: With the ACTIVITY
scope, the NewMessageListener
only works while the chat is visible.
Embed LiveChatView in your layout
You can embed the LiveChatView
directly in your layout for more control over the chat window and its placement, instead of using LiveChat.getInstance().show()
. For full implementation details, refer to the LiveChatActivity.
Here is a short overview of the steps to embed the LiveChatView
in your layout:
1. Add LiveChatView to your layout
Begin with adding <com.livechatinc.chatsdk.src.presentation.LiveChatView />
to your layout XML file.
2. Provide activity or fragment context
During onCreate
of your Activity
or Fragment
, call:
ATTACH CONTEXT
liveChatView.attachTo(this)
This is required to properly handle the view's lifecycle, support file sharing, and launch links in the default external browser.
3. React to visibility events
Provide LiveChatView.InitListener
when initializing the view:
VIEW INIT CALLBACK
liveChatView.init(initCallbackListener)
Migrating from v2.5.0 to 3.0.0
If you're migrating from older SDK versions, here's the breakdown of the most important information you need to take note of:
- The SDK is now Kotlin-based.
- The API is now streamlined and uses the
LiveChat
singleton. - The package changed to
com.livechatinc.chatsdk
.
For the full migration guide, refer to the README available in the SDK's repository.