Messaging UI

Overview

StraaS Messaging UI SDK provides a widget to establish a chatroom ui.

straas-messaging-ui provides a default UI for a chatroom, you can use non-ui SDK straas-messaging instead if you want to customize your chatroom view.

Getting Started

This shows you how to establish a chatroom ui step by step.

Requirement

• Your Activity MUST install AppCompatDelegate, use AppCompatActivity is the first choice.
• For the best practice, FragmentActivity is required. Some features won't be enabled without FragmentActivity.

Project Setting

Dependency

Add dependency on jCenter using Gradle.

X.X.X is your preferred version. For the version information, see CHANGELOG

compile 'io.straas.android.sdk:straas-messaging-ui:X.X.X'

Vector Drawables Backward Compatibility

• Gradle config

//For Gradle Plugin 2.0+
 android {
   defaultConfig {
     vectorDrawables.useSupportLibrary = true
    }
 }

//For Gradle Plugin 1.5 or below
android {
  defaultConfig {
    // Stops the Gradle plugin’s automatic rasterization of vectors
    generatedDensities = []
  }
  // Flag notifies aapt to keep the attribute IDs around
  aaptOptions {
    additionalParameters "--no-version-vectors"
  }
}

Credential

Fill up StraaS SDK-Credential to enable straas-messaging-ui SDK.

Create a chatroom UI

Before 0.4.0

Chatroom UI SDK provides ChatroomView widget to establish a chatroom ui.

• First, define ChatroomView widget in activity layout. (e.g.: activity_main.xml)

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:orientation="vertical"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <io.straas.android.sdk.messaging.ui.ChatroomView
        android:id="@+id/chatroom"
        android:background="@android:color/white"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"/>

</RelativeLayout>

• How to modify ChatroomView background color

You can modify attribute android:background to change ChatroomView background color.

android:background="@android:color/white"

• Next, find ChatroomView view from activity.

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    
    setContentView(R.layout.activity_main);

    ChatroomView chatroom = (ChatroomView) findViewById(R.id.chatroom);
    
    ...
    
}

Since 0.4.0, we divide chatroom UI into ChatroomOutputView & ChatroomInputView

ChatroomOutputView provides messages list presenting, while ChatroomInputView provides user interface related to inputing, e.g. type & send message.

<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
                android:layout_width="match_parent"
                android:layout_height="match_parent">

    <io.straas.android.sdk.messaging.ui.ChatroomOutputView
        android:id="@+id/chat_room"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_above="@android:id/inputArea"/>

    <io.straas.android.sdk.messaging.ui.ChatroomInputView
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_alignParentBottom="true"
        android:id="@android:id/inputArea"/>

</RelativeLayout>

Connect to a chatroom

Before v0.4.0

• After getting ChatroomView in activity, you can invoke connect(...) to connect to a chatroom, ChatroomView adds new messages automatically. ChatroomView also provides getChatRoomManager() to return a ChatRoomManager for non-ui operation.

String targetChannel = "test_chatroom"
Identity identity = new Identity("Put JWT here");
chatroom.connect(targetChannel, identity);

v0.4.0 and later

• To activate ChatroomInputView from ChatroomOutputView, after getting ChatroomOutputView in activity, you can invoke connect(...) to connect to a chatroom, and ChatroomOutputView also provides getChatRoomManager() to return ChatRoomManager. After getting the chatroomManager, you can call chatroomInputView.setChatroomManager(chatroomManager) to activate the ChatroomInputView.

• Besides previous connect(...) function to connect to a chatroom (we keep this interface for backward compatibility). Since 0.4.0, you can also init a chatroomManager (the detail of chatroomManager) then call chatroomOutputView.setChatroomManager(chatroomManager) & chatroomInputView.setChatroomManager(chatroomManager)` for connecting to a chatroom.

• To enable default Sticker Panel, FragmentActivity is required.

// Please add maven repo for showing sticker panel 
maven { url "https://raw.github.com/laenger/maven-releases/master/releases" }

You should inject target chatroom name, Identity in connect(...), and flag in.

• target chatroom name：What chatroom name to connect to.
• Identity：Who connects to this chatroom
• flag：See Connection flag.

Listen events

Chatroom UI SDK provides listeners to learn chatroom status.

• setCredentialAuthorizeListener：When credential do authorization, this listener tell success or failure.

mChatroomOutputView.setCredentialAuthorizeListener(new CredentialAuthorizeListener() {
    @Override
    public void onSuccess(ChatroomManager chatroom) {
        
    }

    @Override
    public void onFailure(CredentialFailReason error) {

    }

    @Override
    public void onFailure(Exception error) {

    }
});

• setSendMessageListener： When message sends, this listener tells success or failure.

chatroomInputView.setSendMessageListener(new OnCompleteListener<Void>() {
    @Override
    public void onComplete(@NonNull Task<Void> task) {
        //handle the result
    }
});

• setEventListener：This listener tell about chatroom status and other events.

chatroom.setEventListener(new EventListener() {
    @Override
    public void onConnected() {}

    @Override
    public void onConnectFailed(Exception error) {}

    @Override
    public void onError(Exception error) {}

    ...

});

More details about callback in listeners, please refer API document.

Disconnect

• If you want to leave the chatroom, remember to call disconnect() method to notify server your leaving.

chatroom.disconnect();

Style

• If you want to set the style of ChatroomOutputView & ChatroomInputView, you can create a style as the name ChatroomTheme to set attributes. Remember to override all of this attributes if you create this style. For example:

    <style name="ChatroomTheme">
        <item name="backgroundColor">@android:color/white</item>
        <item name="msgAuthorColor">@android:color/black</item>
        <item name="msgTextColor">#8b000000</item>
        <item name="msgDividerColor">#EBEBEB</item>
        <item name="msgRelativeTimeColor">#808080</item>
        <item name="textSize">14sp</item>
        <item name="bottomBarColor">#EFEFEF</item>
        <item name="inputHintColor">#808080</item>
        <item name="sendButtonColor">?attr/colorPrimary</item>
        <item name="showAvatar">false</item>
        <item name="relativeTime">true</item>
        <item name="inputMaxLines">4</item>
        <item name="pinnedMessageBackground">#f4f4f4</item>
        <item name="pinnedMessageTextColor">#8b000000</item>
        <item name="pinnedMessagePinIconColor">#FF0000FF</item>
    </style>

backgroundColor will influence the color of background.

msgAuthorColor will influence the color of message author name.

msgTextColor will influence the color of message text.

msgDividerColor will influence the color of message divider.

msgRelativeTimeColor will influence the color of message relative time.

textSize will influence the size of message author name and message text.

bottomBarColor will influence the color of bottom bar.

inputHintColor will influence the color of input hint text.

sendButtonColor will influence the color of send button and input EditText bottom line.

showAvatar will influence the visibility of the avatar. (since 0.4.0)

relativeTime will influence the format of message sending time. (since 0.4.3)

inputMaxLines will influence the max size of input area. (since 0.5.1)

pinnedMessageBackground will influence the background color of pinned message. (since 0.7.12)

pinnedMessageTextColor will influence the text color of pinned message. (since 0.7.12)

pinnedMessagePinIconColor will influence the pin icon color of pinned message. (since 0.7.12)

• For the attributes not listed above, we use mostly the system default value to configure the UI. Here are some examples:
  • If you want to modify the input text color, you can modify ?attr/editTextColor or ?android:attr/textColorPrimary by adding a new theme and with pre-assigned android:editTextColor. You can also check Android official reference and our example.