qiscus sdk android

介紹

Qiscus Chat SDK（軟體開發套件）是 Qiscus 提供的產品，讓您能夠快速輕鬆地將應用程式內聊天/聊天功能嵌入到您的應用程式中。透過我們的聊天 SDK，您可以實現聊天功能，而無需處理即時通訊基礎設施的複雜性。我們提供強大的 API，讓您可以在最無縫的開發過程中將聊天功能實現到您的應用程式中。

Qiscus Chat SDK 提供許多功能，例如：

• 一對一聊天
• 群聊
• 頻道聊天
• 打字指示器
• 圖片和文件附件
• 在線狀態
• 交貨收據
• 閱讀收據
• 刪除留言
• 離線留言
• 封鎖用戶
• 自訂即時事件
• 伺服器端與伺服器 API 和 Webhook 集成
• 在您的應用程式中嵌入機器人引擎
• 啟用推播通知
• 從您的應用程式匯出和匯入訊息

嘗試範例應用程式

我們提供了一個範例應用程式來幫助您了解我們的聊天 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。按一下此處造訪您的儀表板

入門

步驟1：取得您的APP ID

首先，您需要透過造訪 Qiscus Chat Dashboard 在儀表板中建立應用程式。您可以建立多個應用程式 ID。

第 2 步：安裝 Qiscus 聊天 SDK

Qiscus Chat SDK 至少需要 Android API 16 (Jelly Bean)。要將您的應用程式與 Qiscus 集成，只需兩（兩）步即可完成。首先，您需要在 .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'
}

步驟3：初始化Qiscus Chat SDK

在進行身份驗證之前，您需要為聊天應用程式啟動您的APP ID。此初始化只需在應用程式生命週期中完成​​一次。初始化可以在初次啟動時進行。您可以按照以下方法執行此操作：

 public class SampleApp extends Application {

    @ Override
    public void onCreate () {
        super . onCreate ();

        QiscusCore . initWithAppId ( this , APPID );

  }
 }

初始化應該在 Android 應用程式中呼叫一次。您可以在應用課程中採用的最佳實踐。

第 4 步：向 Qiscus 進行身份驗證

要使用 Qiscus 聊天 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，也無法存取使用者資料。

使用者名稱（字串）：用於在聊天室中顯示名稱的使用者名稱。

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 聊天 SDK 可以建立 3 種類型的聊天室：一對一聊天室、群組聊天室和頻道。在某些情況下，可以透過房間唯一 ID 或房間名稱來識別房間。

一對一聊天室

我們假設您已經認識要與之聊天的目標用戶。確保您的目標使用者已透過 setUser() 方法在 Qiscus Chat SDK 中註冊，如上一節所述。若要與目標使用者開始對話，可以使用getChatRoom()方法來完成。然後，Qiscus 聊天 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 ：可以作為聊天室附加資訊的元數據，由鍵值組成，例如鍵：背景，值：紅色。

群聊室

當您希望許多用戶在一對一聊天室中一起聊天時，您需要建立群組房間。基本上，Group Room 與 1 對 1 聊天室的概念相同，但不同之處在於 Group Room 將在單一方法中定位 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 時，它將使用預設值。但是，在第二次呼叫（房間確實存在）並且您發送 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 );

之後，您需要註冊 FCM token 來通知 Qiscus Chat SDK，您可以在登入後在主頁（在 qiscus 中登入）呼叫 sendCurrentToken()，例如：

 if ( Qiscus . hasSetupUser ()) {
    FirebaseUtil . sendCurrentToken ();
}

 public class FirebaseUtil {

    public static void sendCurrentToken() {
        AppFirebaseMessagingService.getCurrentDeviceToken();
    }
}

• 也在 Manifest 中加入 .AppFirebaseMessagingService，例如：

 <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 支援

對於喜歡使用 RXJava 進行編碼的您，Qiscus Chat SDK 支援 RXJava。因此，您可以像使用 Native 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
      });