qiscus sdk android
v1.8.3
Qiscus Chat SDK (Software Development Kit) adalah produk yang disediakan oleh Qiscus yang memungkinkan Anda menyematkan fitur chat/obrolan dalam aplikasi pada aplikasi Anda dengan cepat dan mudah. Dengan SDK obrolan kami, Anda dapat mengimplementasikan fitur obrolan tanpa harus berurusan dengan kompleksitas infrastruktur komunikasi waktu nyata. Kami menyediakan API canggih yang memungkinkan Anda menerapkan fitur obrolan ke dalam aplikasi Anda dalam proses pengembangan yang paling lancar.
Qiscus Chat SDK menyediakan banyak fitur seperti:
Kami telah menyediakan contoh aplikasi untuk membantu Anda mengenal SDK obrolan kami. Contoh aplikasi ini dibuat dengan fungsionalitas penuh sehingga Anda dapat mengetahui alur dan aktivitas utama menggunakan Qiscus Chat SDK. Sekarang Anda dapat dengan bebas menyesuaikan UI Anda sendiri. Anda juga dapat membuat aplikasi Anda sendiri di atas aplikasi sampel kami. Untuk lebih jelasnya anda dapat mendownload contoh ini.
git clone https://github.com/qiscus/qiscus-chat-sdk-android-sample.git
Aplikasi contoh ini menggunakan contoh ID APLIKASI, artinya dengan menggunakan aplikasi contoh ini, Anda akan berbagi data dengan orang lain. Jika Anda ingin mencobanya sendiri, Anda dapat mengubah ID APLIKASI menjadi ID APLIKASI Anda sendiri. Anda dapat menemukan ID APLIKASI Anda di dasbor Anda. Klik di sini untuk mengakses dasbor Anda
Pertama, Anda perlu membuat aplikasi Anda di dashboard, dengan mengakses Dashboard Qiscus Chat. Anda dapat membuat lebih dari satu ID Aplikasi.
Qiscus Chat SDK memerlukan minimal Android API 16 (Jelly Bean). Untuk mengintegrasikan aplikasi Anda dengan Qiscus dapat dilakukan dalam 2 (dua) langkah. Pertama, Anda perlu menambahkan referensi URL di proyek .gradle Anda. Referensi ini adalah panduan bagi .gradle untuk mendapatkan Qiscus Chat SDK dari repositori yang tepat. Di bawah ini adalah cara melakukannya:
allprojects {
repositories {
...
maven { url "https://artifactory.qiscus.com/artifactory/qiscus-library-open-source" }
}
}
Kedua, Anda perlu menambahkan dependensi SDK di dalam aplikasi Anda .gradle. Kemudian, Anda perlu melakukan sinkronisasi untuk mengkompilasi Qiscus Chat SDK untuk aplikasi Anda.
dependencies {
...
implementation 'com.qiscus.sdk:chat-core:1.8.3'
}
Anda perlu memulai ID APLIKASI untuk aplikasi obrolan Anda sebelum melakukan otentikasi. Inisialisasi ini hanya perlu dilakukan satu kali dalam siklus hidup aplikasi. Inisialisasi dapat diimplementasikan pada awal startup. Inilah cara Anda melakukannya:
public class SampleApp extends Application {
@ Override
public void onCreate () {
super . onCreate ();
QiscusCore . initWithAppId ( this , APPID );
}
}Inisialisasi harus dipanggil satu kali di seluruh aplikasi Android. Praktik terbaik yang dapat Anda terapkan di kelas aplikasi.
Untuk menggunakan fitur Qiscus Chat SDK, pengguna perlu melakukan otentikasi ke Server Qiscus, untuk detail lebih lanjut Anda dapat mengetahui bagian Otentikasi. Otentikasi ini dilakukan dengan memanggil fungsi setUser(). Fungsi ini akan mengambil atau membuat kredensial pengguna berdasarkan userId unik, misalnya:
QiscusCore . setUser ( userId , userKey )
. withUsername ( username )
. withAvatarUrl ( avatarUrl )
. withExtras ( extras )
. save ( new QiscusCore . SetUserListener () {
@ Override
public void onSuccess ( QiscusAccount qiscusAccount ) {
//on success
}
@ Override
public void onError ( Throwable throwable ) {
//on error
});Di mana:
userId (string, unik): Pengidentifikasi pengguna yang akan digunakan untuk mengidentifikasi pengguna dan digunakan kapan pun pengguna lain perlu mengobrol dengan pengguna ini. Bisa apa saja, apakah itu email pengguna, indeks basis data pengguna Anda, dll. Asalkan unik dan berupa string.
userKey (string): userKey untuk tujuan otentikasi, jadi meskipun orang asing mengetahui ID pengguna Anda, dia tidak dapat mengakses data pengguna.
nama pengguna (string): Nama pengguna untuk nama tampilan di dalam tujuan Ruang Obrolan.
avatarURL (string, opsional): untuk menampilkan avatar pengguna, kembali ke avatar default jika tidak disediakan.
Anda dapat belajar dari gambar di bawah ini untuk memahami apa yang sebenarnya terjadi saat memanggil fungsi setUser() :
Setelah akun pengguna Anda dibuat, terkadang Anda mungkin perlu memperbarui informasi pengguna, seperti mengubah avatar pengguna. Anda dapat menggunakan metode QiscusCore.updateUser() untuk melakukan perubahan pada akun Anda.
QiscusCore . updateUser ( userName , avatarUrl , new QiscusCore . SetUserListener () {
@ Override
public void onSuccess ( QiscusAccount qiscusAccount ) {
//do anything after it successfully updated
}
@ Override
public void onError ( Throwable throwable ) {
//do anything if error occurs
}
});Seperti disebutkan di bagian sebelumnya, ketika Anda melakukan setUser(), data pengguna akan disimpan secara lokal. Ketika pengguna perlu memutuskan sambungan dari layanan Qiscus Chat SDK, Anda perlu menghapus data pengguna yang terkait dengan Qiscus Chat SDK, seperti token, profil, pesan, ruangan, dll, dari perangkat lokal. Anda dapat melakukan ini dengan memanggil metode clearUser() :
QiscusCore . clearUser ();Ruang Obrolan adalah tempat di mana 2 pengguna atau lebih dapat mengobrol satu sama lain. Ada 3 jenis Ruang Obrolan yang dapat dibuat menggunakan Qiscus Chat SDK: Ruang Obrolan 1 lawan 1, Ruang Obrolan Grup, dan Saluran. Untuk beberapa kasus, sebuah ruangan dapat diidentifikasi berdasarkan id unik ruangan atau nama ruangan.
Kami berasumsi bahwa Anda sudah mengetahui pengguna target yang ingin Anda ajak ngobrol. Pastikan pengguna yang Anda targetkan telah terdaftar di Qiscus Chat SDK melalui metode setUser() seperti yang dijelaskan pada bagian sebelumnya. Untuk memulai percakapan dengan pengguna yang Anda targetkan, dapat dilakukan dengan metode getChatRoom() . Qiscus Chat SDK, kemudian, akan menyajikan Anda Ruang Obrolan baru, secara asinkron. Ketika ruangan berhasil dibuat, Qiscus Chat SDK akan mengembalikan paket Ruang Obrolan melalui pendengar onSuccess() .
QiscusApi . getInstance (). chatUser ( userId , options )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
// on error
});Di mana:
userId : Pengidentifikasi pengguna yang akan digunakan untuk mengidentifikasi pengguna dan digunakan kapan pun pengguna lain perlu mengobrol dengan pengguna ini. Bisa apa saja, apakah email pengguna, indeks database pengguna Anda, dll. Asalkan unik dan berupa string.
distinctId : (tidak berlaku lagi) anda dapat mengisi “ ” (string kosong).
options : metadata yang dapat menjadi informasi tambahan pada Chat Room yang berisi key-value, misalnya key: background, dan value: red.
Jika Anda ingin banyak pengguna mengobrol bersama dalam ruang obrolan 1 lawan 1, Anda perlu membuat Ruang Grup. Pada dasarnya Group Room memiliki konsep yang sama dengan 1-on-1 Chat Room, namun perbedaannya adalah Group Room akan menargetkan array userId dalam satu metode. Berikut cara membuat Ruang Grup:
QiscusApi . getInstance (). createGroupChat ( roomName , userIds , avatarUrl , options );
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
// on error
});Membuat Channel Chat Room sangat ideal untuk use case yang membutuhkan jumlah partisipan yang banyak, lebih dari 100 orang.
Anda perlu mengatur UniqueId untuk mengidentifikasi Ruang Obrolan Saluran. Jika Ruang Obrolan dengan Id unik yang telah ditentukan sebelumnya tidak ada, maka Ruang Obrolan baru akan dibuat dengan pemohon sebagai satu-satunya peserta. Jika tidak, jika Ruang Obrolan dengan Id unik yang telah ditentukan sebelumnya sudah ada, ruang tersebut akan dikembalikan dan peminta akan ditambahkan sebagai peserta.
Jika ruangan tidak ada pada panggilan pertama dan Anda tidak mengirimkan avatarUrl dan/atau RoomName, nilai default akan digunakan. Namun, setelah panggilan kedua (ruangan memang ada) dan Anda mengirim avatarUrl dan/atau Namakamar, nilai tersebut akan diperbarui. Misalnya implementasi pembuatan saluran:
QiscusApi . getInstance (). createChannel ( uniqueId , roomName , avatarUrl , options )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
// on error
});Dalam beberapa kasus, Anda mungkin perlu menambahkan peserta tambahan ke dalam obrolan ruang Anda atau bahkan mengeluarkan peserta mana pun.
Untuk mendapatkan semua daftar ruangan, Anda dapat memanggil QiscusApi.getInstance().getChatRooms(int page, int limit, boolean showMembers), halaman dimulai dari 1, limit menunjukkan maksimal ruangan per halaman, showMembers juga merupakan tanda untuk memuat anggota ruang atau tidak. Berikut contoh kode:
QiscusApi . getInstance (). getAllChatRooms ( showParticipant , showRemoved , showEmpty , page , limit )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRooms -> {
//on success
}, throwable -> {
//on error
});Anda dapat menambahkan lebih dari satu peserta di Ruang Obrolan dengan memanggil metode addRoomMember. Anda juga dapat meneruskan beberapa ID pengguna. Setelah peserta berhasil bergabung dengan Ruang Obrolan, mereka akan mendapatkan Ruang Obrolan baru di daftar Ruang Obrolan mereka.
QiscusApi . getInstance (). addParticipants ( roomId , userId )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
//on error
});Anda dapat menghapus lebih dari satu peserta di Ruang Obrolan dengan memanggil metode hapusRoomMember. Anda juga dapat meneruskan beberapa userId. Setelah peserta dikeluarkan dari Ruang Obrolan, mereka tidak akan menemukan Ruang Obrolan terkait di daftar Ruang Obrolan mereka.
QiscusApi . getInstance (). removeParticipants ( roomId , userId )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
//success
}, throwable -> {
//error
});Pertama instal FCM ke aplikasi Anda, Anda dapat mengikuti langkah-langkah ini. Anda dapat melewati langkah ini jika aplikasi Anda sudah menggunakan FCM. Kemudian letakkan kunci api Anda ke dashboard qiscus. Sekarang mari kita integrasikan dengan SDK klien Qiscus, pertama-tama aktifkan FCM di konfigurasi obrolan Qiscus.
Qiscus . getChatConfig (). setEnableFcmPushNotification ( true );Setelah itu, Anda perlu mendaftarkan token FCM untuk memberi tahu Qiscus Chat SDK, Anda dapat memanggil sendCurrentToken() setelah login dan di halaman beranda (sedang login di qiscus), misalnya:
if ( Qiscus . hasSetupUser ()) {
FirebaseUtil . sendCurrentToken ();
} public class FirebaseUtil {
public static void sendCurrentToken() {
AppFirebaseMessagingService.getCurrentDeviceToken();
}
}
<service android:name=".AppFirebaseMessagingService"
android:exported="true">
<intent-filter>
<action android:name="com.google.firebase.MESSAGING_EVENT" />
</intent-filter>
</service>
Setelah mendaftarkan token FCM, Anda akan mendapatkan data dari FCM Qiscus Chat SDK, yang dapat Anda tangani dengan menggunakan metode handleMessageReceived() , misalnya:
import android.util.Log;
import androidx.annotation.NonNull;
import com.google.firebase.messaging.FirebaseMessaging;
import com.google.firebase.messaging.FirebaseMessagingService;
import com.google.firebase.messaging.RemoteMessage;
import com.qiscus.sdk.chat.core.QiscusCore;
import com.qiscus.sdk.chat.core.util.QiscusFirebaseMessagingUtil;
public class AppFirebaseMessagingService extends FirebaseMessagingService {
@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
super.onMessageReceived(remoteMessage);
Log.d("Qiscus", "onMessageReceived " + remoteMessage.getData().toString());
if (QiscusFirebaseMessagingUtil.handleMessageReceived(remoteMessage)) {
return;
}
}
@Override
public void onNewToken(@NonNull String s) {
super.onNewToken(s);
Log.d("Qiscus", "onNewToken " + s);
QiscusCore.registerDeviceToken(s);
}
public static void getCurrentDeviceToken() {
final String token = QiscusCore.getFcmToken();
if (token != null) {
FirebaseMessaging.getInstance().deleteToken()
.addOnCompleteListener(task -> {
QiscusCore.removeDeviceToken(token);
getTokenFcm();
})
.addOnFailureListener(e -> QiscusCore.registerDeviceToken(token));
} else {
getTokenFcm();
}
}
private static void getTokenFcm() {
FirebaseMessaging.getInstance().getToken()
.addOnCompleteListener(task -> {
if (task.isSuccessful() && task.getResult() != null) {
QiscusCore.registerDeviceToken(task.getResult());
} else {
Log.e("Qiscus", "getCurrentDeviceToken Failed : " +
task.getException());
}
});
}
}
Qiscus Chat SDK menyediakan cara sederhana untuk memungkinkan aplikasi mempublikasikan dan mendengarkan beberapa peristiwa real-time. Anda dapat mempublikasikan pengetikan, pembacaan, status pengguna, acara khusus sehingga Anda dapat menanganinya dengan bebas di pengendali acara. Hal ini memungkinkan Anda memberi tahu pengguna bahwa peserta lain terlibat aktif dalam berkomunikasi dengan mereka.
Qiscus Chat SDK menggunakan EventBus untuk menyiarkan acara ke seluruh aplikasi. Anda dapat mempelajari lebih lanjut tentang EventBus di situs web ini. Yang perlu Anda lakukan adalah mendaftarkan objek yang akan menerima event dari EventBus. Anda dapat menyebutnya seperti ini:
EventBus . getDefault (). register ( this );Setelah Anda tidak perlu lagi mendengarkan acara tersebut, Anda harus membatalkan pendaftaran penerima dengan memanggil metode ini:
EventBus . getDefault (). unregister ( this );Ini adalah contoh cara mendaftarkan aktivitas untuk menerima acara dari EventBus:
public class MyActivity extends AppCompatActivity {
@ Override
protected void onCreate ( @ Nullable Bundle savedInstanceState ) {
super . onCreate ( savedInstanceState );
setContentView ( R . layout . activity_my );
// listen room event
QiscusPusherApi . getInstance (). subscribeChatRoom ( qiscusChatRoom );
// listen user status
QiscusPusherApi . getInstance (). subscribeUserOnlinePresence ( "userId" );
}
@ 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
}
@ Subscribe
public void onReceiveRoomEvent ( QiscusChatRoomEvent roomEvent ) {
switch ( roomEvent . getEvent ()) {
case TYPING :
roomEvent . getRoomId (); // this is the room id
roomEvent . getUser (); // this is the qiscus user id
roomEvent . isTyping (); // true if the user is typing
break ;
case DELIVERED :
roomEvent . getRoomId (); // this is the room id
roomEvent . getUser (); // this is the qiscus user id
roomEvent . getCommentId (); // the comment id was delivered
break ;
case READ :
roomEvent . getRoomId (); // this is the room id
roomEvent . getUser (); // this is the qiscus user id
roomEvent . getCommentId (); // the comment id was read
break ;
case CUSTOM :
//here, you can listen custom event
roomEvent . getRoomId (); // this is the room id
roomEvent . getUser (); // this is the qiscus user id
roomEvent . getEventData (); //event data (JSON)
break ;
}
}
@ Subscribe
public void onUserStatusChanged ( QiscusUserStatusEvent event ) {
event . getUser (); // this is the qiscus user id
event . isOnline (); // true if user is online
event . getLastActive (); // Date of last active user
}
@ Override
protected void onDestroy () {
super . onDestroy ();
// stop listening room event
QiscusPusherApi . getInstance (). unsubsribeChatRoom ( qiscusChatRoom );
// stop listening user status
QiscusPusherApi . getInstance (). unsubscribeUserOnlinePresence ( "qiscus_user_id" );
}
}ProGuard adalah pengoptimal paling populer untuk bytecode Java. Itu membuat aplikasi Java dan Android Anda lebih kecil dan lebih cepat. Baca di sini untuk detail lebih lanjut tentang Proguard. Jika Anda menggunakan Proguard dalam aplikasi Anda, pastikan Anda menambahkan aturan Proguard Qiscus dari Aturan Qiscus Proguard ke aturan Proguard Anda.
Bagi Anda yang lebih suka coding dengan RXJava, Qiscus Chat SDK memang mendukung RXJava. Jadi, Anda bisa melakukan apa saja seperti yang Anda lakukan dengan Native Java. Misalnya untuk mengatur pengguna, seperti yang telah dijelaskan di bagian Otentikasi Dasar, Anda dapat melakukan hal yang sama dengan RXJava. Berikut contoh bagaimana Anda dapat mengatur pengguna dengannya:
// Setup qiscus account with rxjava example
Qiscus . setUser ( "[email protected]" , "password" )
. withUsername ( "Tony Stark" )
. withAvatarUrl ( "http://avatar.url.com/handsome.jpg" )
. save ()
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( qiscusAccount -> {
//do anything if success
}, throwable -> {
//do anything if error occurs
});
