qiscus sdk android
v1.8.3
Qiscus Chat SDK (ソフトウェア開発キット) は、Qiscus が提供する製品で、アプリ内チャット/チャット機能をアプリケーションにすばやく簡単に組み込むことができます。チャット SDK を使用すると、リアルタイム通信インフラストラクチャの複雑さに対処することなくチャット機能を実装できます。最もシームレスな開発プロセスでアプリにチャット機能を実装できる強力な API を提供します。
Qiscus Chat SDK は、次のような多くの機能を提供します。
チャット SDK を理解するのに役立つサンプル アプリを提供しました。このサンプル アプリは、Qiscus Chat SDK を使用してフローと主なアクティビティを理解できるように、完全な機能を備えて構築されています。独自のUIを自由にカスタマイズできるようになりました。サンプル アプリの上に独自のアプリを構築することもできます。詳細については、このサンプルをダウンロードしてください。
git clone https://github.com/qiscus/qiscus-chat-sdk-android-sample.git
このサンプル アプリはサンプル APP ID を使用します。つまり、このサンプル アプリを使用すると、他のユーザーとデータを共有することになります。自分で試してみたい場合は、APP ID を自分の APP ID に変更できます。 APP ID はダッシュボードで確認できます。ここをクリックしてダッシュボードにアクセスしてください
まず、Qiscus チャット ダッシュボードにアクセスして、ダッシュボードでアプリケーションを作成する必要があります。複数のアプリ ID を作成できます。
Qiscus Chat SDK には、少なくとも Android API 16 (Jelly Bean) が必要です。アプリを Qiscus と統合するには、2 つの手順で実行できます。まず、.gradle プロジェクトに URL 参照を追加する必要があります。このリファレンスは、.gradle が適切なリポジトリから Qiscus Chat SDK を取得するためのガイドです。その方法は以下のとおりです。
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 を開始する必要があります。この初期化は、アプリのライフサイクルで 1 回だけ行う必要があります。初期化は初回起動時に実施できます。その方法は次のとおりです。
public class SampleApp extends Application {
@ Override
public void onCreate () {
super . onCreate ();
QiscusCore . initWithAppId ( this , APPID );
}
}初期化は Android アプリ全体で 1 回呼び出す必要があります。アプリケーション クラスに取り入れられるベスト プラクティス。
Qiscus Chat SDK 機能を使用するには、ユーザーは Qiscus Server に対して認証する必要があります。詳細については、「認証」セクションを参照してください。この認証は、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 (文字列): 認証目的の userKey なので、見知らぬ人があなたのユーザー ID を知ったとしても、ユーザー データにアクセスすることはできません。
ユーザー名(文字列): チャット ルーム内での表示名として使用するユーザー名。
avatarURL (文字列、オプション): ユーザーのアバターを表示するには、指定されていない場合はデフォルトのアバターにフォールバックします。
以下の図から、 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()リスナーを通じて Chat Room パッケージを返します。
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 人を超える多数の参加者が必要なユースケースに最適です。
チャネル チャット ルームを識別するには uniqueId を設定する必要があります。事前定義されたuniqueIdを持つチャット ルームが存在しない場合は、要求者を唯一の参加者として新しいチャット ルームを作成します。それ以外の場合、事前定義されたuniqueIdを持つチャット ルームがすでに存在する場合は、そのルームが返され、要求者が参加者として追加されます。
最初の呼び出し時にルームが存在せず、avatarUrl や roomName を送信しない場合は、デフォルト値が使用されます。ただし、2 回目の呼び出し後 (ルームは存在します)、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 から始まり、limit はページごとの最大ルームを示します。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 について詳しくは、この Web サイトをご覧ください。行う必要があるのは、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 を使用している場合は、必ず Qiscus Proguard Rules から 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
});
