qiscus sdk android
v1.8.3
Qiscus Chat SDK(소프트웨어 개발 키트)는 앱 내 채팅/채팅 기능을 애플리케이션에 빠르고 쉽게 내장할 수 있도록 Qiscus에서 제공하는 제품입니다. Chat SDK를 사용하면 실시간 커뮤니케이션 인프라의 복잡성을 처리하지 않고도 채팅 기능을 구현할 수 있습니다. 우리는 가장 원활한 개발 프로세스에서 앱에 채팅 기능을 구현할 수 있도록 강력한 API를 제공합니다.
Qiscus Chat SDK는 다음과 같은 다양한 기능을 제공합니다.
채팅 SDK에 대해 알아보는 데 도움이 되는 샘플 앱을 제공했습니다. 이 샘플 앱은 Qiscus Chat SDK를 사용하여 흐름과 주요 활동을 파악할 수 있도록 모든 기능을 갖추고 구축되었습니다. 이제 자신만의 UI를 자유롭게 커스터마이징할 수 있습니다. 또한 샘플 앱 위에 자신만의 앱을 구축할 수도 있습니다. 자세한 내용을 보려면 이 샘플을 다운로드하세요.
git clone https://github.com/qiscus/qiscus-chat-sdk-android-sample.git
이 샘플 앱은 샘플 앱 ID를 사용합니다. 즉, 이 샘플 앱을 사용하면 다른 사람과 데이터를 공유하게 됩니다. 직접 시도해보고 싶다면 앱 ID를 자신의 앱 ID로 변경할 수 있습니다. 대시보드에서 앱 ID를 확인할 수 있습니다. 대시보드에 액세스하려면 여기를 클릭하세요.
먼저 Qiscus Chat Dashboard에 접속하여 대시보드에 애플리케이션을 생성해야 합니다. 두 개 이상의 앱 ID를 생성할 수 있습니다.
Qiscus Chat SDK에는 최소 Android API 16(Jelly Bean)이 필요합니다. 앱을 Qiscus와 통합하려면 2단계로 완료할 수 있습니다. 먼저 .gradle 프로젝트에 URL 참조를 추가해야 합니다. 이 참조는 올바른 저장소에서 Qiscus Chat SDK를 가져오기 위한 .gradle 가이드입니다. 그 방법은 다음과 같습니다.
allprojects {
repositories {
...
maven { url "https://artifactory.qiscus.com/artifactory/qiscus-library-open-source" }
}
}
둘째, 앱 .gradle 내에 SDK 종속성을 추가해야 합니다. 그런 다음 앱용 Qiscus Chat SDK를 컴파일하려면 동기화해야 합니다.
dependencies {
...
implementation 'com.qiscus.sdk:chat-core:1.8.3'
}
인증을 진행하기 전에 채팅 앱의 APP ID를 시작해야 합니다. 이 초기화는 앱 수명 주기에서 한 번만 수행하면 됩니다. 초기화는 초기 시작 시 구현할 수 있습니다. 그렇게 하는 방법은 다음과 같습니다.
public class SampleApp extends Application {
@ Override
public void onCreate () {
super . onCreate ();
QiscusCore . initWithAppId ( this , APPID );
}
}초기화는 Android 앱 전체에서 한 번 호출되어야 합니다. 응용 프로그램 수업에 넣을 수 있는 모범 사례입니다.
Qiscus Chat SDK 기능을 사용하려면 사용자가 Qiscus 서버에 인증해야 합니다. 자세한 내용은 인증 섹션을 참조하세요. 이 인증은 setUser() 함수를 호출하여 수행됩니다. 이 함수는 고유한 userId를 기반으로 사용자 자격 증명을 검색하거나 생성합니다. 예를 들면 다음과 같습니다.
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
});어디:
userId (문자열, 고유): 사용자를 식별하는 데 사용되고 다른 사용자가 이 사용자와 채팅해야 할 때마다 사용되는 사용자 식별자입니다. 사용자 이메일, 사용자 데이터베이스 색인 등 무엇이든 가능합니다. 고유하고 문자열이면 됩니다.
userKey (string): 인증을 위한 userKey이므로 낯선 사람이 귀하의 사용자 ID를 알고 있더라도 사용자 데이터에 접근할 수 없습니다.
사용자 이름 (문자열): 채팅방 내 표시 이름을 위한 사용자 이름입니다.
아바타URL (문자열, 선택 사항): 사용자의 아바타를 표시하고, 제공되지 않은 경우 기본 아바타로 대체합니다.
setUser() 함수를 호출할 때 실제로 무슨 일이 일어났는지 이해하기 위해 아래 그림을 통해 배울 수 있습니다.
사용자 계정이 생성된 후 때로는 사용자 아바타 변경 등 사용자 정보를 업데이트해야 할 수도 있습니다. QiscusCore.updateUser() 메소드를 사용하여 계정을 변경할 수 있습니다.
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
}
});이전 섹션에서 언급했듯이 setUser()를 수행하면 사용자의 데이터가 로컬에 저장됩니다. 사용자가 Qiscus Chat SDK 서비스 연결을 끊어야 하는 경우 토큰, 프로필, 메시지, 방 등 Qiscus Chat SDK와 관련된 사용자 데이터를 로컬 장치에서 삭제해야 합니다. ClearUser() 메소드를 호출하여 이를 수행할 수 있습니다.
QiscusCore . clearUser ();채팅방 은 2명 이상의 사용자가 서로 채팅을 할 수 있는 공간입니다. Qiscus Chat SDK를 사용하여 생성할 수 있는 채팅방은 1:1 채팅방, 그룹 채팅방, 채널 3가지 유형이 있습니다. 어떤 경우에는 방의 고유 ID나 방 이름으로 방을 식별할 수 있습니다.
우리는 당신이 채팅하고 싶은 대상 사용자를 이미 알고 있다고 가정합니다. 이전 섹션에서 설명한 대로 setUser() 메소드를 통해 대상 사용자가 Qiscus Chat SDK에 등록되었는지 확인하세요. 대상 사용자와 대화를 시작하려면 getChatRoom() 메소드를 사용하면 됩니다. Qiscus Chat SDK는 비동기식으로 새로운 채팅방을 제공합니다. 방이 성공적으로 생성되면 Qiscus Chat SDK는 onSuccess() 리스너를 통해 채팅방 패키지를 반환합니다.
QiscusApi . getInstance (). chatUser ( userId , options )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
// on error
});어디:
userId : 사용자를 식별하는 데 사용되고 다른 사용자가 이 사용자와 채팅해야 할 때마다 사용되는 사용자 식별자입니다. 사용자의 이메일, 사용자 데이터베이스 색인 등 무엇이든 될 수 있습니다. 고유하고 문자열이면 됩니다.
UniqueId : (더 이상 사용되지 않음) “ ”(빈 문자열)을 채울 수 있습니다.
options : 채팅방에 추가 정보로 사용될 수 있는 메타데이터로, 키-값으로 구성됩니다(예: 키: 배경, 값: 빨간색).
다수의 사용자가 1:1 채팅방에서 함께 대화를 나누고 싶다면 그룹룸을 생성해야 합니다. 기본적으로 단체방은 1:1 채팅방과 동일한 개념이지만, 단체방은 단일 방식으로 userId 배열을 대상으로 한다는 점이 다릅니다. 그룹룸을 만드는 방법은 다음과 같습니다.
QiscusApi . getInstance (). createGroupChat ( roomName , userIds , avatarUrl , options );
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
// on error
});채널 채팅방을 생성하는 것은 100명 이상의 많은 참가자가 필요한 사용 사례에 이상적입니다.
채널 채팅방을 식별하려면 고유 ID를 설정해야 합니다. 사전 정의된 고유 ID가 있는 채팅방이 존재하지 않으면 요청자가 유일한 참가자인 새 채팅방이 생성됩니다. 그렇지 않고 사전 정의된 고유 ID가 있는 채팅방이 이미 존재하는 경우 해당 방을 반환하고 요청자를 참가자로 추가합니다.
첫 번째 호출 시 룸이 존재하지 않고 AvatarUrl 및/또는 roomName을 보내지 않으면 기본값이 사용됩니다. 그러나 두 번째 호출(방이 존재함) 후에 AvatarUrl 및/또는 roomName을 전송하면 해당 값으로 업데이트됩니다. 예를 들어 구현 생성 채널은 다음과 같습니다.
QiscusApi . getInstance (). createChannel ( uniqueId , roomName , avatarUrl , options )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
// on error
});경우에 따라 회의실 채팅에 참가자를 추가하거나 참가자를 제거해야 할 수도 있습니다.
모든 방 목록을 얻으려면 QiscusApi.getInstance().getChatRooms(int page, int Limit, boolean showMembers)를 호출할 수 있습니다. 페이지는 1부터 시작하고 제한은 페이지당 최대 방을 나타내며 showMembers는 로드 룸 구성원에 대한 플래그이기도 합니다. 샘플 코드는 다음과 같습니다.
QiscusApi . getInstance (). getAllChatRooms ( showParticipant , showRemoved , showEmpty , page , limit )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRooms -> {
//on success
}, throwable -> {
//on error
});addRoomMember 메소드를 호출하여 채팅방에 참가자를 추가할 수 있습니다. 여러 userId를 전달할 수도 있습니다. 참가자가 채팅방에 성공적으로 참여하면 채팅방 목록에 새 채팅방이 표시됩니다.
QiscusApi . getInstance (). addParticipants ( roomId , userId )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
//on error
});RemoveRoomMember 메소드를 호출하여 채팅방에서 한 명 이상의 참가자를 제거할 수 있습니다. 여러 userId를 전달할 수도 있습니다. 참가자가 채팅방에서 제거되면 해당 채팅방 목록에서 관련 채팅방을 찾을 수 없습니다.
QiscusApi . getInstance (). removeParticipants ( roomId , userId )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
//success
}, throwable -> {
//error
});먼저 앱에 FCM을 설치하고 다음 단계를 따르세요. 앱에서 이미 FCM을 사용하는 경우 이 단계를 건너뛸 수 있습니다. 그런 다음 API 키를 Qiscus 대시보드에 넣으세요. 이제 Qiscus 클라이언트 SDK와 통합하고 먼저 Qiscus 채팅 구성에서 FCM을 활성화해 보겠습니다.
Qiscus . getChatConfig (). setEnableFcmPushNotification ( true );그런 다음 Qiscus Chat SDK에 알리려면 FCM 토큰을 등록해야 합니다. 로그인 후 홈 페이지(qiscus에 로그인한 경우)에서 sendCurrentToken()을 호출할 수 있습니다. 예를 들면 다음과 같습니다.
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>
FCM 토큰을 등록한 후 FCM Qiscus Chat SDK에서 데이터를 가져옵니다. 예를 들어, handleMessageReceived() 메소드를 사용하여 처리할 수 있습니다.
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는 애플리케이션이 일부 실시간 이벤트를 게시하고 수신할 수 있는 간단한 방법을 제공합니다. 이벤트 핸들러에서 자유롭게 처리할 수 있도록 타이핑, 읽기, 사용자 상태, 커스텀 이벤트를 공개할 수 있습니다. 이를 통해 다른 참가자가 적극적으로 통신하고 있음을 사용자에게 알릴 수 있습니다.
Qiscus Chat SDK는 전체 애플리케이션에 이벤트를 방송하기 위해 EventBus를 사용합니다. 이 웹사이트에서 EventBus에 대해 자세히 알아볼 수 있습니다. 당신이 해야 할 일은 EventBus로부터 이벤트를 수신할 객체를 등록하는 것입니다. 다음과 같이 호출할 수 있습니다.
EventBus . getDefault (). register ( this );더 이상 이벤트를 수신할 필요가 없으면 다음 메서드를 호출하여 수신자를 등록 취소해야 합니다.
EventBus . getDefault (). unregister ( this );다음은 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는 Java 바이트코드에 대한 가장 널리 사용되는 최적화 프로그램입니다. Java 및 Android 애플리케이션을 더 작고 빠르게 만듭니다. Proguard에 대한 자세한 내용은 여기를 참조하세요. 애플리케이션에서 Proguard를 사용하는 경우 Qiscus Proguard 규칙의 Qiscus Proguard 규칙을 Proguard 규칙에 추가해야 합니다.
RXJava로 코딩하는 것을 선호하는 사용자를 위해 Qiscus Chat SDK는 RXJava를 지원합니다. 따라서 네이티브 Java를 사용하는 것처럼 무엇이든 할 수 있습니다. 예를 들어 기본 인증 섹션에서 설명한 대로 사용자를 설정하려면 RXJava를 사용하여 동일한 작업을 수행할 수 있습니다. 다음은 사용자를 설정하는 방법의 예입니다.
// 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
});
