LiveChat SDK for Android

A Android SDK for integrating LiveChat functionality into your mobile application.

LiveChat: https://developers.livechat.com/docs/getting-started/installing-livechat/android-widget/

Table of contents

1. Getting started
   1. Requirements
   2. Usage
      1. Install SDK
      2. Initialize
      3. Show Chat
2. Customer information
3. Unread message counter
4. UI Customization
   1. Localizing text
   2. Custom error view
   3. Customizing Activity
5. Clearing chat session
6. Handling links
7. Troubleshooting
   1. Reacting to errors
   2. Logger
8. Advanced usage
   1. LiveChatView lifecycle modes
   2. Embedding LiveChatView
9. Migrating from v2.5.0 to 3.0.0

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.

Requirements

LiveChat SDK is compatible:

• Android 5.0 (API level 21) or higher
• Java 8 or higher

Usage

Follow these steps to integrate LiveChat into your Android application:

Install SDK:

Add the JitPack repository to your root build.gradle

allprojects {
   repositories {
      maven { url 'https://jitpack.io' }
   }
}

Add dependency to your app's build.gradle:

dependencies {
    implementation 'com.github.livechat:chat-window-android:3.0.0-rc1'
}

Add Internet permission to AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

Initialize:

Initialize the SDK in the onCreate() method of your Application instance

LiveChat.initialize("<LICENSE>", this)

Show Chat

Show the the chat to a customer

LiveChat.getInstance().show()

That's it! Your customer can already start chatting with you.

Customer information

Pre-fill the pre-chat form and provide customer details to your agents by setting customer information. All information is optional. Group ID defaults to 0 if not provided.

LiveChat.getInstance().setCustomerInfo(
            "Joe", // Name
            "[email protected]", // Email
            "0", // Group ID, defaults to "0"
            Collections.singletonMap("internalCustomerId", "ABC123") // Any additional custom parameters
        )

Note: You must provide this information before calling LiveChat.show()

Unread message counter

Use com.livechatinc.chatsdk.src.domain.listeners.NewMessageListener to get notified about new messages in the chat

Set it wherever you want to react on new message, like increase badge count

LiveChat.getInstance().setNewMessageListener()

UI Customization

While chat appearance and language settings are managed through the Agent App, you can customize how errors are displayed to users

Localizing text

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 here

Custom error view

To completely change the error view, you can also override the default one by including live_chat_error_layout.xml in your app's layout resources.

Note: Your custom view must contain a View with live_chat_error_button id

Customizing Activity

Activity will follow your activity's theme. To change activity configuration you can just override the activity declaration in your app AndroidManifest.xml

Clearing chat session

Chat window uses WebView's cookies to store the session. To clear the chat session, you can call:

LiveChat.clearSession()

Handling links

By default, links sent between your Agents and Customers are opened in the default browser. If you want to intercept the link and handle it in your app, provide your UrlHandler

LiveChat.getInstance().setUrlHandler(object : UrlHandler {
    override fun handleUrl(uri: Uri): Boolean {
        // Return true if handled, false to open in default browser
        return false
    }
})

Troubleshooting

React to errors

To monitor and handle issues related to loading the chat view, you can set an error listener. 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.

LiveChat.getInstance().setErrorListener { error ->
   // Handle the error
}

Logger

Configure the logging level to help with debugging and troubleshooting. Set the desired level before initializing LiveChat: Refer to Logger for available log levels.

Logger.setLogLevel(Logger.LogLevel.VERBOSE);

Note: Network calls require at least INFO. DEBUG and VERBOSE provide maximum level of detail

File picker activity not found

In case you want to react or track instances where activity for file picking on user device is not found, you can set a listener for this event:

LiveChat.getInstance().setFileChooserNotFoundListener {
   Log.e("Example", "File chooser not found. Please check your configuration.")
}

Advanced usage

For more control over the SDK integration, consider these advanced options. Note that they require additional implementation steps: If you need to use the following usage, please let us know about your use case. We would love to hear from you!

LiveChatView lifecycle modes

By default, after LiveChat.show() the view is inflated and kept in memory. This allows reacting to new messages as described in Unread message counter. If you don't need that feature and want to free up memory once chat is no longer visible, you can use LiveChatViewLifecycleMode to control the lifecycle of the view. You should specify the mode when initializing.

LiveChat.initialize("<LICENSE>", this, LiveChatViewLifecycleMode.WHEN_SHOWN)

Note: Using WHEN_SHOWN mode will disable the NewMessageListener no longer works when chat is not visible.

Embedding LiveChatView

You can directly embed LiveChatView in your layout, instead of showing it in activity (LiveChat.show()). This allows you to have more control over the chat window and its placement in your app. There are additional steps and requirements you need to follow to take full advantage of chat window. Generally you can refer to LiveChatActivity for the implementation details, but here is a quick overview of the steps you need to take.

Embed in your layout

Add <com.livechatinc.chatsdk.LiveChatView /> your layout XML file

Provide activity or fragment context

During onCreate of your Activity or Fragment call

liveChatView.attachTo(this)

Note: this is required to properly handle the lifecycle of the view, support file sharing and launch links in default external browser

React to visibility events

Provide LiveChatViewInitListener when initializing the view

liveChatView.init(initCallbackListener)

Migrating from v2.5.0 to 3.0.0

Key Changes

• Kotlin-based SDK
• Streamlined API for easier integration
• Package name changed from com.livechatinc.inappchat to com.livechatinc.chatsdk
• Updated API for initializing and configuring the chat
• Edge-to-edge display support
• Enhanced error handling

Steps

Update your dependency

dependencies {
    implementation 'com.github.livechat:chat-window-android:3.0.0'
}

Note: With version 3 we no longer use "v" prefix

Update Configuration

The new API uses LiveChat singleton instead of ChatWindowConfiguration and it's split into two parts: initialization and customer information setup.

Update activity declaration if needed

Update event listeners

The old ChatWindowEventsListener has removed. Some of the callbacks are no longer needed, the rest has been split into individual callbacks

• onWindowInitialized() -> removed for recommended integration. If you're embedding the view directly see Embedding LiveChatView for details
• onChatWindowVisibilityChanged -> removed recommended integration. If you're embedding the view directly see Embedding LiveChatView for details
• onNewMessage -> replaced with NewMessageListener
• onRequestAudioPermissions -> removed
• onError -> replaced with ErrorListener
• handleUri -> replaced with UriHandler
• onFilePickerActivityNotFound -> FileChooserActivityNotFoundListener

For a complete example of implementation, please refer to the example app included in the repository.

v2.x.x

v2 of the library is still available on JitPack. You can find documentation by selecting v2.x.x tag in the repository