MENU
Developers Consoleopen_in_new

Introduction

This documentation will cover embedding a mobile chat window in an Android application.

Installation

To get the project into your build, do the following:

1. Add the JitPack repository

See the repository at JitPack

Add it to your root build.gradle at the end of repositories:

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

2. Add the dependency

To add the dependency, use the following code:

dependencies {
    compile 'com.github.livechat:chat-window-android:v2.0.0'
}

Your application will need a permission to use the Internet. Add the following line to your AndroidManifest.xml:

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

If you want to allow users to upload files from their external storage using the chat window, a permission is needed as well:

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

Usage

You can use this library in a couple of ways. To be able to use all features, we recommend you to add the chat window as a view, either by using a static method which adds the view to your Activity, or as an embedded view in your xml.

When ChatWindowView is initilized, you will get the events when a new message arrives.

First, let's configure the chat window.

Configuration

The configuration is very simple - just use ChatWindowConfiguration.java constructor. Note that the licence number is mandatory.

configuration = new ChatWindowConfiguration(
    "your_licence_number", 
    "group_id", 
    "Visitor name", 
    "visitor@email.com", 
    customParamsMap
);

Chat Window View

There are two recommended ways to use the ChatWindow:

Full Screen Window

All you need to do is to create, attach and initialize the chat window. For example:

public void startFullScreenChat() {
    if (fullScreenChatWindow == null) {
        fullScreenChatWindow = ChatWindowView.createAndAttachChatWindowInstance(getActivity());
        fullScreenChatWindow.setUpWindow(configuration);
        fullScreenChatWindow.setUpListener(this);
        fullScreenChatWindow.initialize();
    }
    fullScreenChatWindow.showChatWindow();
}

XML Embedded View

If you want to control the location and size of the ChatWindowView, you may want to add it to your app either by including a view in XML:

<com.livechatinc.inappchat.ChatWindowView
    android:id="@+id/embedded_chat_window"
    android:layout_width="match_parent"
    android:layout_height="400dp"/>

or by inflating the view directly:

ChatWindowView chatWindowView = new ChatWindowView(MainActivity.this);

and then initializing the ChatWindow with the full screen window approach:

public void startEmmbeddedChat(View view) {
    if (!emmbeddedChatWindow.isInitialized()) {
        emmbeddedChatWindow.setUpWindow(configuration);
        emmbeddedChatWindow.setUpListener(this);
        emmbeddedChatWindow.initialize();
    }
    emmbeddedChatWindow.showChatWindow();
}

Depending on your use case you may want to hide the ChatWindow if a user hits the back button. You can use our onBackPressed() function which hides the view if it's visible and returns true. Add the following to your activity/fragment:

@Override
public boolean onBackPressed() {
    return fullScreenChatWindow != null && fullScreenChatWindow.onBackPressed();
}

File sharing

If you want the users to be able to send files, you need to set ChatWindowEventsListener on your ChatWindowView and allow the view to handle the activity result:

@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (fullChatWindow != null) fullChatWindow.onActivityResult(requestCode, resultCode, data);
    super.onActivityResult(requestCode, resultCode, data);
}

ChatWindowEventsListener

This listener allows you to:

Alternative usage

Note: This option has limited capabilities.

If you don't need the chat to work in the background nor to receive messages when the window is minimized, use Activity and Fragment chat window described above.

If you don't want the chat window to reload its content every time a device orientation changes, add this line to your Activity in the manifest:

android:configChanges="orientation|screenSize"

The chat window will handle the orientation change by itself.

Example usage

There are two ways to open the chat window – by using an Activity or a Fragment.

Activity

In order to open a chat window in a new Activity, you need to declare ChatWindowActivity in your manifest. Add the following line to AndroidManifest.xml, between <application></application> tags:

    <activity android:name="com.livechatinc.inappchat.ChatWindowActivity" android:configChanges="orientation|screenSize" />

Finally, add the following code to your application, in the place where you want to open the chat window (e.g. button listener). You need to provide a Context (your Activity or Application object), your LiveChat licence number (taken from the tracking code) and, optionally, the ID of a group:

    Intent intent = new Intent(context, com.livechatinc.inappchat.ChatWindowActivity.class);
    intent.putExtra(com.livechatinc.inappchat.ChatWindowActivity.KEY_GROUP_ID, "your_group_id");
    intent.putExtra(com.livechatinc.inappchat.ChatWindowActivity.KEY_LICENSE_NUMBER, "your_license_number");
    context.startActivity(intent);

It’s also possibile to automatically login to the chat window by providing visitor’s name and email. You need to disable pre-chat survey in the web application and add the following lines to the previous code:

    intent.putExtra(com.livechatinc.inappchat.ChatWindowActivity.KEY_VISITOR_NAME, "your_name");
    intent.putExtra(com.livechatinc.inappchat.ChatWindowActivity.KEY_VISITOR_EMAIL, "your_email");

Fragment

In order to open chat window in a new Fragment, you need to add the following code to your application, in the place where you want to open the chat window (e.g. button listener). You also need to provide your LiveChat licence number and a group ID:

    getFragmentManager() 
       .beginTransaction() 
       .replace(R.id.frame_layout, ChatWindowFragment.newInstance("your_license_number", "your_group_id"), "chat_fragment") 
       .addToBackStack("chat_fragment") 
       .commit();

ChatWindowFragment.newInstance() method returns the chat window Fragment.

It’s also possible to automatically login to the chat window by providing visitor’s name and email. You need to disable pre-chat survey in the web application and use a different newInstance() method:

    getFragmentManager() 
       .beginTransaction() 
       .replace(R.id.frame_layout, ChatWindowFragment.newInstance("your_license_number", "your_group_id", visitor _name, visitor _email), "chat_fragment") 
       .addToBackStack("chat_fragment") 
       .commit();

Sample application

This sample app will display a chat trigger button. Once clicked, a chat window with your support team will be opened in the app.

You can refer to our sample app in the module. There are examples for three usage cases:

In app widget example In app widget example

Possible use-cases include: adding a chat button to your “Contact us” screen or displaying a chat button all the time within the app. Read more about providing in-app support in mobile applications.

Translation

You can change or translate error messages by defining your own string resources with the following IDs:

<string name="failed_to_load_chat">Couldn\'t load chat.</string>
<string name="cant_share_files">File sharing is not configured for this app</string>