Qiscus Chat SDK for Android

The Qiscus Chat SDK allows developers to embed real-time chat features into Android applications without managing the underlying communication infrastructure.

Key Capabilities:

• Built-in UI: Provides a customizable Chat Room UI out of the box. Note that you are responsible for building your own Contact List and Conversation List UIs using the data provided by the SDK.
• Core Features: Includes private/group chat, typing indicators, delivery/read receipts, image/file attachments, online presence, emoji support, and message deletion.
• Advanced Extensibility: Supports server-side integration via Webhooks/Server API, bot engine embedding, push notifications, and message import/export.

The Qiscus Chat SDK enables real-time communication through a messaging flow where users register to the Qiscus Server, open a chat room, and exchange messages.

Key Concepts

• Messaging Flow: Users send messages to a Chat Room. Other participants in that room receive the message via event handlers (e.g., on receive message, read receipt).
• APP ID: A unique identifier for your application. It acts as the bridge that connects users across different platforms (iOS, Android, Web). Users within the same APP ID can communicate with each other, but users in different Qiscus applications cannot.
• Environments: New APP IDs are initially created as trial/sandbox environments. To ensure continuous access and additional sandbox APP IDs, you may need to upgrade to a paid plan.

Chat Rooms in the Qiscus Chat SDK support an options parameter, which consists of string key-value pairs. This metadata is automatically synchronized across all participants in a conversation.

Best Practices:

• Keep the amount of data in options to a minimum to ensure fast synchronization.
• Use it for non-critical UI or contextual data, such as setting a room's background color or storing latitude/longitude coordinates.

Example keys/values: key: background, value: red.

The Qiscus SDK uses EventBus to broadcast events throughout your application. To receive events, you must register your object (e.g., an Activity or Fragment) with the EventBus and unregister it when it is no longer needed to prevent memory leaks.

To listen for specific events, create a method annotated with @Subscribe where the parameter type matches the event class you wish to intercept.

@Override
protected void onResume() {
    super.onResume();
    EventBus.getDefault().register(this); // register to EventBus
}

@Override
protected void onPause() {
    super.onPause();
    EventBus.getDefault().unregister(this); // unregister from EventBus
}

@Subscribe
public void onReceiveComment(QiscusCommentReceivedEvent event) {
    event.getQiscusComment(); // to get the comment
}

The SDK is composed of three primary layers that handle different data and communication needs:

1. QiscusCore: The main entry point. It manages the library lifecycle, user setup, and provides helper methods for chat rooms and configuration.
2. QiscusApi: Handles remote interactions via HTTP requests. Use this to access server-side data like chat rooms and to send messages. Note that these methods return rx.Observable (RxJava) and do not affect local data.
3. QiscusPusherApi: Handles real-time events via MQTT (e.g., typing indicators, message read receipts, online status). Events are dispatched via EventBus (check com.qiscus.sdk.event).
4. QiscusDataStore: Manages local data storage. This allows for offline access and improved UX (e.g., showing cached messages immediately while fetching new ones from the server).

Qiscus supports three main types of chat rooms. Choose based on your use case requirements:

• 1-on-1 Chat Room: Private chat between two users. Supports blocking.
• Group Chat Room: Targeted at an array of user IDs. Supports adding/removing participants.
• Channel: Allows users to join without invitation (e.g., public forums).

The Qiscus Chat SDK uses EventBus (by GreenRobot) to broadcast real-time events throughout your application. This allows you to listen for events like typing indicators, message read statuses, user online status, and custom events.

To use the event system, you must:

1. Register your object (e.g., an Activity or Fragment) with the EventBus.
2. Unregister the object when it is no longer needed to prevent memory leaks.
3. Subscribe to specific events by creating methods annotated with @Subscribe where the parameter type matches the event class you want to handle.

// Registering
EventBus.getDefault().register(this);

// Unregistering
EventBus.getDefault().unregister(this);

To use only the Core SDK (without the full UI features), update your build.gradle and change the initialization class from Qiscus to QiscusCore.

dependencies {
    implementation 'com.qiscus.sdk:chat-core:1.3.4'
}

// Change from:
Qiscus.init(this, "yourappid");

// To:
QiscusCore.init(this, "yourappid");

The Sample Dashboard is a PHP-based tool used for user management and demonstrating how to interact with the Qiscus Server API. To run it locally, you need PHP and Composer installed.

1. Clone the repository:

   git clone https://github.com/qiscus/dashboard-sample.git
   cd dashboard-sample

2. Install dependencies and start the server:

   composer install
   php -S localhost:8000

3. To connect the dashboard to your own app, update the APP_ID and Secret Key inside the .env file using credentials from your Qiscus SDK dashboard.

To understand the full functionality and flow of the SDK, you can use the official sample application. You can customize the UI or build your own application on top of it.

Note: The sample app uses a shared sample APP ID. If you want to test with your own data, replace it with your own APP ID from the Qiscus Dashboard.

git clone https://bitbucket.org/qiscus/qiscus-sdk-core-android-sample.git