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
      });