- Android Studio v4.1.3 or latest
- Min sdk 16
- Target sdk 31
- compailer Java 11
- Kotlin v1.3.50
- build gradle 7.1.2
Add this URL reference in your project build.gradle
allprojects {
repositories {
google()
mavenCentral()
gradlePluginPortal()
maven {
url "https://artifactory.qiscus.com/artifactory/qiscus-library-open-source"
}
}
}
Then add this to your app build.gradle
dependencies {
...
implementation 'com.qiscus.multichannel:multichannel-widget:2.2.0'
In order to use QiscusMultichannelWidget, you need to initialize it with your AppID (YOUR_APP_ID). Get more information to get AppID from here
class SampleApp : Application() {
lateinit var qiscusMultichannelWidget: QiscusMultichannelWidget
override fun onCreate() {
super.onCreate()
val qiscusCore = QiscusCore()
qiscusMultichannelWidget = QiscusMultichannelWidget.setup(this, qiscusCore, "YOUR_APP_ID", "LOCALPREFKEY")
...
}
}
LOCALPREFKEY : local data identifier
After the initialization, you can access all the widget's functions.
Set UserId before start the chat, this is mandatory.
qiscusMultichannelWidget.setUser("UserId", "displayName", "avatarUrl")
If you want to set user properties, you can set them by using this function, for example:
val userProperties = mapOf("city" to "jogja", "job" to "developer")
qiscusMultichannelWidget.setUser("user_id", "display_name", "avatar_url", userProperties)
You can check whether the user has already logged in.
qiscusMultichannelWidget.isLoggedIn()
Use this function to start a chat.
qiscusMultichannelWidget.initiateChat()
.setRoomTitle("Custom Title")
.setRoomSubtitle(
QiscusMultichannelWidgetConfig.RoomSubtitle.EDITABLE,
"Custom subtitle"
)
.startChat(Context)
startChat (Context) : method to initiate chat and open Multichannel Widget Chat Room Activity
// 1
qiscusMultichannelWidget.initiateChat()
.automaticSendMessage("testing automatic")
//2
val messageModel = QMessage()
qMessage.text = "testing automatic"
qiscusMultichannelWidget.initiateChat()
.automaticSendMessage(qMessage)
//3
qiscusMultichannelWidget.initiateChat()
.manualSendMessage("testing manual")
Use this function to clear the logged-in users.
qiscusWidget.clearUser()
configure system message visibility by calling setShowSystemMessage(isShowing: Boolean).
qiscusWidget.initiateChat()
...
.setShowSystemMessage(false)
...
.startChat(Context)
We provide several functions to customize the User Interface.
| Title | Description |
|---|---|
| setRoomTitle | Set room name base on customer's name or static default. |
| setRoomSubTitle | |
| setRoomSubTitle(RoomSubtitle.Enabled) | Set enable room sub name by the system. |
| setRoomSubTitle(RoomSubtitle.Disabled) | Set disable room sub name. |
| setRoomSubTitle(RoomSubtitle.Editable, "Custom subtitle") | Set enable room sub name base on static default. |
| setHideUIEvent | Show/hide system event. |
| setAvatar | |
| setAvatar(Avatar.Enable) | Set enable avatar and name |
| setAvatar(Avatar.Disabled) | Set disable avatar and name |
| setEnableNotification | Set enable app notification. |
| No | Title | Description |
|---|---|---|
| 1 | setNavigationColor | Set navigation color. |
| 2 | setSendContainerColor | Set icon send border-color. |
| 3 | setFieldChatBorderColor | Set field chat border-color. |
| 4 | setSendContainerBackgroundColor | Set send container background-color. |
| 5 | setNavigationTitleColor | Set room title, room subtitle, and back button border color. |
| 6 | setSystemEventTextColor | Set system event text and border color. |
| 7 | setLeftBubbleColor | Set left bubble chat color (for: Admin, Supervisor, Agent). |
| 8 | setRightBubbleColor | Set right bubble chat color (Customer). |
| 9 | setLeftBubbleTextColor | Set left bubble text color (for: Admin, Supervisor, Agent). |
| 10 | setRightBubbleTextColor | Set right bubble text color (Customer). |
| 11 | setTimeLabelTextColor | Set time text color. |
| 12 | setTimeBackgroundColor | Set time background color. |
| 13 | setBaseColor | Set background color of the room chat. |
| 14 | setEmptyTextColor | Set empty state text color. |
| 15 | setEmptyBackgroundColor | Set empty state background color. |
Follow these steps to set push notifications on your application
- Setup Firebase to Your Android App
If you already have setup Firebase in your Android app, you can skip this step and go to next step which is Generate FCM Server key. Otherwise, you can setup Firebase to your Android app by following these steps.
- Get FCM Server Key in Firebase Console
You can get FCM Server Key by following these steps:
- Go to Firebase Console
- Click your projects to see the overview your
- On the top of left panel, click the gear icon on Project Overview menu. From the drop-down menu, click Project Settings.
- Click the Cloud Messaging tab under Settings. On the Project Credentials, find and copy your Server Key.
- Setup FCM Server Key in The Qiscus Multichannel Dashboard
You can set FCM Secret Key by following these steps:
- Go to Qiscus Multichannel Chat page to register your email
- Log in to Qiscus Multichannel Chat with yout email and password
- Go to ‘Setting’ menu on the left bar
- Look for ‘Notification’
- Click Android's Customer Widget Push Notification
- In the Android (FCM Server Key) section, click +Add FCM Server Key to add your FCM Server Key,
- Paste FCM Server Key value and click Save change
NOTE One App Id can only be associated with one FCM Project, make sure the FCM Server keys are from the same FCM Project, If you already put multiple FCM server keys but they are different FCM project, then our system deletes the related device token and the effect you will not receive FCM notification.
- Register Your FCM Token to Qiscus Multichannel Widget
- First you need to enable FCM for your app by calling configuration, for example:
val config = QiscusMultichannelWidgetConfig()
.setEnableNotification(true) // default is true
.setNotificationListener(object : MultichannelNotificationListener {
override fun handleMultichannelListener(context: Context?, qiscusComment: QMessage?) {
// show your notification here
}
})
.setNotificationIcon(R.drawable.*ic_notification*)
- set configuration before calling QiscusMultichannelWidget.setup(), for example:
// input the configuration
QiscusMultichannelWidget.setup(application, qiscusCore, "YOUR_APP_ID", config, color, "LOCALPREFKEY")
- To enable FCM in ChatConfig, you need to register FCM token to notify Qiscus Multicahnnel Widget, for example:
class FirebaseServices : FirebaseMessagingService() {
override fun onNewToken(newToken: String) {
super.onNewToken(newToken)
QiscusMultichannelWidget.instance.registerDeviceToken(
qiscusCore, newToken
)
}
}
- You need to make sure every time open the app, the FCM token always needs to be registered in Qiscus Multicahnnel Widget. To retrieve the current FCM token, you can see below code:
FirebaseMessaging.getInstance().token
.addOnCompleteListener OnCompleteListener@{ task: Task<String?> ->
if (!task.isSuccessful) {
Log.e("Qiscus", "getCurrentDeviceToken Failed : " + task.exception)
return@OnCompleteListener
}
if (task.isSuccessful && task.result != null) {
val currentToken = task.result
currentToken?.let {
QiscusMultichannelWidget.instance.registerDeviceToken(
qiscusMultiChatEngine.get(MULTICHANNEL_CORE), it
)
}
}
}
- Add the service.FirebaseServices in Manifest, for example:
<service android:name="com.qiscus.multichannel.sample.widget.service.FirebaseServices">
<intent-filter>
<action android:name="com.google.firebase.MESSAGING_EVENT" />
</intent-filter>
</service>
NOTE Make sure always to register FCM token when open the app
- Handle Incoming Message From Push Notification
After registering your FCM token, you will get data from FCM Qiscus Multicahnnel Widget, you can handle by using isMultichannelMessage() function, for example
class FirebaseServices : FirebaseMessagingService() {
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
if (QiscusMultichannelWidget.instance.isMultichannelMessage(
remoteMessage, allQiscusCore
)
) {
return
}
}
}
- Manage access to data stored
Add the provider in Manifest, for example:
<provider
android:name="androidx.core.content.FileProvider"
android:authorities="${applicationId}"
android:exported="false"
android:grantUriPermissions="true">
<meta-data
android:name="android.support.FILE_PROVIDER_PATHS"
android:resource="@xml/qiscus_provider_paths" />
</provider>
if your app using Proguard, make sure you add Proguard Rules of Qiscus Multichannel widget from Qiscus Multichannel widget Proguard Rules to your Proguard Rules
If you facing error like this
`More than one file was found with OS independent path 'META-INF/rxjava.properties'`
Add this to your app build.gradle
`android {
.....
.....
packagingOptions {
exclude 'META-INF/rxjava.properties'
}
} `
- Get your APPID
- Go to Qiscus Multichannel Chat page to register your email
- Log in to Qiscus Multichannel Chat with yout email and password
- Go to ‘Setting’ menu on the left bar
- Look for ‘App Information’
- You can find APPID in the App Info
- Activate Qiscus Widget Integration
- Go to ‘Integration’ menu on the left bar
- Look for ‘Qiscus Widget’
- Slide the toggle to activate the Qiscus widget
- Set YOUR_APP_ID in the Example
- Open SampleApp.kt
- Replace the appId with YOUR_ APP_ID (step 1)
qiscusMultichannelWidget = QiscusMultichannelWidget.setup(application, qiscusCore, "YOUR_APP_ID", "LOCALPREFKEY")
- Start Chat
The Example is ready to use. You can start to chat with your agent from the Qiscus Multichannel Chat dashboard.