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.

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:

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

Next, add dependency to your app's build.gradle:

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

Then, add Internet permission to AndroidManifest.xml:

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

Initialization

You can initialize the SDK in the onCreate() method of your Application instance:

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

Display the chat window

The function below allows you to display a chat to a customer:

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.

LiveChat.getInstance().setCustomerInfo(
    "Joe", // Name
    "joe@mail.com", // Email
    "0", // Group ID, defaults to "0"
    Collections.singletonMap("internalCustomerId", "ABC123") // Custom params
)

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.

LiveChat.getInstance().newMessageListener =
    NewMessageListener { message, isChatShown ->
        // Handle new message
    }

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:

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.

LiveChat.getInstance().urlHandler =
        UrlHandler { url ->
            // Return true if handled, false to open in browser
            return@UrlHandler false
        }

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.

LiveChat.getInstance().errorListener = ErrorListener { error ->
    // Handle the error
}

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.setLogLevel(Logger.LogLevel.VERBOSE)

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:

LiveChat.getInstance().filePickerNotFoundListener = FilePickerActivityNotFoundListener {
    // Handle file picker activity not found
}

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:

LiveChat.initialize("<LICENSE>", this, lifecycleScope = LiveChatViewLifecycleScope.ACTIVITY)

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:

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:

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.