qiscus sdk android
v1.8.3
Qiscus Chat SDK (kit de desarrollo de software) es un producto proporcionado por Qiscus que le permite incorporar una función de chat/chat dentro de sus aplicaciones de forma rápida y sencilla. Con nuestro SDK de chat, puede implementar la función de chat sin tener que lidiar con la complejidad de la infraestructura de comunicación en tiempo real. Proporcionamos una API potente que le permite implementar la función de chat en sus aplicaciones en el proceso de desarrollo más fluido.
Qiscus Chat SDK proporciona muchas funciones como:
Hemos proporcionado una aplicación de muestra para ayudarle a conocer nuestro SDK de chat. Esta aplicación de muestra está diseñada con funcionalidades completas para que pueda determinar el flujo y las actividades principales utilizando Qiscus Chat SDK. Ahora puedes personalizar libremente tu propia interfaz de usuario. También puede crear su propia aplicación sobre nuestra aplicación de muestra. Para obtener más detalles, puede descargar este ejemplo.
git clone https://github.com/qiscus/qiscus-chat-sdk-android-sample.git
Esta aplicación de muestra utiliza un ID de aplicación de muestra, lo que significa que, al utilizar esta aplicación de muestra, compartirá los datos con otras personas. En caso de que quiera probarlo usted mismo, puede cambiar el ID de la APLICACIÓN por su propio ID de la APLICACIÓN. Puede encontrar el ID de su aplicación en su panel de control. Haga clic aquí para acceder a su panel de control
Primero, debe crear su aplicación en el panel, accediendo al Panel de chat de Qiscus. Puede crear más de una ID de aplicación.
Qiscus Chat SDK requiere un mínimo de Android API 16 (Jelly Bean). Para integrar tu aplicación con Qiscus, puedes hacerlo en 2 (dos) pasos. Primero, debe agregar una referencia URL en su proyecto .gradle. Esta referencia es una guía para que .gradle obtenga el SDK de Qiscus Chat del repositorio correcto. A continuación se muestra cómo hacerlo:
allprojects {
repositories {
...
maven { url "https://artifactory.qiscus.com/artifactory/qiscus-library-open-source" }
}
}
En segundo lugar, debe agregar dependencias del SDK dentro de su aplicación .gradle. Luego, debe sincronizar para compilar el SDK de Qiscus Chat para su aplicación.
dependencies {
...
implementation 'com.qiscus.sdk:chat-core:1.8.3'
}
Debe iniciar su ID de aplicación para su aplicación de chat antes de realizar la autenticación. Esta inicialización solo debe realizarse una vez en el ciclo de vida de la aplicación. La inicialización se puede implementar en el inicio inicial. Así es como puedes hacerlo:
public class SampleApp extends Application {
@ Override
public void onCreate () {
super . onCreate ();
QiscusCore . initWithAppId ( this , APPID );
}
}La inicialización debe llamarse una vez en una aplicación de Android. Las mejores prácticas que puedes poner en la clase de aplicación.
Para utilizar las funciones del SDK de Qiscus Chat, el usuario debe autenticarse en el servidor Qiscus; para obtener más detalles, puede consultar la sección Autenticación. Esta autenticación se realiza llamando a la función setUser(). Esta función recuperará o creará una credencial de usuario basada en el ID de usuario único, por ejemplo:
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
});Dónde:
userId (cadena, único): un identificador de usuario que se utilizará para identificar a un usuario y se utilizará siempre que otro usuario necesite chatear con este usuario. Puede ser cualquier cosa, ya sea el correo electrónico del usuario, el índice de su base de datos de usuario, etc. Siempre que sea único y una cadena.
userKey (cadena): clave de usuario para fines de autenticación, por lo que incluso si un extraño conoce su ID de usuario, no puede acceder a los datos del usuario.
nombre de usuario (cadena): nombre de usuario para mostrar el nombre dentro de la sala de chat.
avatarURL (cadena, opcional): para mostrar el avatar del usuario, recurra al avatar predeterminado si no se proporciona.
Puede aprender de la siguiente figura para comprender lo que realmente sucedió al llamar a la función setUser() :
Después de crear su cuenta de usuario, a veces es posible que necesite actualizar la información de un usuario, como cambiar el avatar del usuario. Puede utilizar el método QiscusCore.updateUser() para realizar cambios en su cuenta.
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
}
});Como se mencionó en la sección anterior, cuando hizo setUser(), los datos del usuario se almacenarán localmente. Cuando el usuario necesita desconectarse del servicio Qiscus Chat SDK, debe borrar los datos del usuario relacionados con Qiscus Chat SDK, como token, perfil, mensajes, salas, etc., del dispositivo local. Puedes hacer esto llamando al método clearUser():
QiscusCore . clearUser ();La sala de chat es un lugar donde 2 o más usuarios pueden chatear entre sí. Hay 3 tipos de salas de chat que se pueden crear usando Qiscus Chat SDK: sala de chat 1 a 1, sala de chat grupal y canal. En algunos casos, una habitación se puede identificar mediante una identificación única o el nombre de la habitación.
Asumimos que ya conoce a un usuario específico con el que desea chatear. Asegúrese de que su usuario objetivo haya sido registrado en Qiscus Chat SDK a través del método setUser(), como se explica en la sección anterior. Para iniciar una conversación con su usuario objetivo, puede hacerlo con el método getChatRoom() . Qiscus Chat SDK, entonces, le ofrecerá una nueva sala de chat, de forma asincrónica. Cuando la sala se crea correctamente, Qiscus Chat SDK devolverá un paquete de sala de chat a través del oyente onSuccess() .
QiscusApi . getInstance (). chatUser ( userId , options )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
// on error
});Dónde:
userId : un identificador de usuario que se utilizará para identificar a un usuario y se utilizará siempre que otro usuario necesite chatear con este usuario. Puede ser cualquier cosa, ya sea el correo electrónico del usuario, el índice de su base de datos de usuario, etc. Siempre que sea único y una cadena.
distintivoId : (en desuso) puede completar " " (cadena vacía).
opciones : metadatos que pueden ser información adicional para la sala de chat, que consta de clave-valor, por ejemplo, clave: fondo y valor: rojo.
Cuando desee que muchos usuarios conversen juntos en una sala de chat 1 a 1, deberá crear una sala de grupo. Básicamente, la Sala de grupo tiene el mismo concepto que la Sala de chat 1 a 1, pero la diferencia es que la Sala de grupo se enfocará en una variedad de ID de usuario en un solo método. Aquí cómo puedes crear una sala de grupo:
QiscusApi . getInstance (). createGroupChat ( roomName , userIds , avatarUrl , options );
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
// on error
});Crear una sala de chat de canal es ideal para un caso de uso que requiere una gran cantidad de participantes, más de 100.
Debe configurar un Id único para identificar una sala de chat del canal. Si no existe una sala de chat con un ID único predefinido, se creará una nueva con el solicitante como único participante. De lo contrario, si ya existe una sala de chat con un ID único predefinido, devolverá esa sala y agregará al solicitante como participante.
Cuando la sala no existe en la primera llamada y no envía avatarUrl y/o roomName, utilizará el valor predeterminado. Pero, después de la segunda llamada (la sala existe) y envía avatarUrl y/o roomName, se actualizará a ese valor. Por ejemplo, la implementación del canal de creación:
QiscusApi . getInstance (). createChannel ( uniqueId , roomName , avatarUrl , options )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
// on error
});En algunos casos, es posible que necesites agregar participantes adicionales al chat de tu sala o incluso eliminar a algún participante.
Para obtener la lista de todas las salas, puede llamar a QiscusApi.getInstance().getChatRooms(int page, int limit, boolean showMembers), la página comienza desde 1, el límite indica las salas máximas por página, showMembers es un indicador para cargar miembros de la sala también o no. Aquí código de muestra:
QiscusApi . getInstance (). getAllChatRooms ( showParticipant , showRemoved , showEmpty , page , limit )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRooms -> {
//on success
}, throwable -> {
//on error
});Puede agregar más de un participante en la sala de chat llamando al método addRoomMember. También puede pasar varios ID de usuario. Una vez que un participante logra unirse a la sala de chat, obtendrá una nueva sala de chat en su lista de salas de chat.
QiscusApi . getInstance (). addParticipants ( roomId , userId )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
//on error
});Puede eliminar a más de un participante en la sala de chat llamando al método removeRoomMember. También puede pasar varios ID de usuario. Una vez que se elimina a un participante de la sala de chat, no encontrará la sala de chat relacionada en su lista de salas de chat.
QiscusApi . getInstance (). removeParticipants ( roomId , userId )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
//success
}, throwable -> {
//error
});Primero instale FCM en sus aplicaciones, puede seguir estos pasos. Puede omitir este paso si sus aplicaciones ya usan FCM. Luego coloque su clave API en el panel de qiscus. Ahora integremos con el SDK del cliente Qiscus, primero habilite FCM en la configuración de chat de Qiscus.
Qiscus . getChatConfig (). setEnableFcmPushNotification ( true );Después de eso, necesita registrar el token FCM para notificar a Qiscus Chat SDK, puede llamar a sendCurrentToken() después de iniciar sesión y en la página de inicio (antes de iniciar sesión en qiscus), por ejemplo:
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>
Después de registrar su token FCM, obtendrá datos del SDK de chat de FCM Qiscus, que puede manejar utilizando el método handleMessageReceived() , por ejemplo:
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 proporciona una forma sencilla de permitir que las aplicaciones publiquen y escuchen algunos eventos en tiempo real. Puede publicar escritura, lectura, estado de usuario y eventos personalizados para que pueda manejarlos libremente en el controlador de eventos. Esto le permite informar a los usuarios que otro participante participa activamente en comunicarse con ellos.
Qiscus Chat SDK utiliza EventBus para transmitir eventos a todas las aplicaciones. Puede obtener más información sobre EventBus en este sitio web. Lo que debes hacer es registrar el objeto que recibirá el evento de EventBus. Puedes llamarlo así:
EventBus . getDefault (). register ( this );Una vez que ya no necesites escuchar el evento, debes cancelar el registro del receptor llamando a este método:
EventBus . getDefault (). unregister ( this );Este es un ejemplo de cómo registrar una actividad para recibir eventos de 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 es el optimizador más popular para el código de bytes de Java. Hace que sus aplicaciones Java y Android sean más pequeñas y rápidas. Lea aquí para obtener más detalles sobre Proguard. Si está utilizando Proguard en su aplicación, asegúrese de agregar las reglas Proguard de Qiscus de las Reglas de Qiscus Proguard a sus reglas de Proguard.
Para aquellos que prefieren codificar con RXJava, Qiscus Chat SDK es compatible con RXJava. Por lo tanto, puede hacer cualquier cosa como lo hace con Java nativo. Por ejemplo, para configurar un usuario, como se explicó en la sección Autenticación básica, puede hacer lo mismo con RXJava. Aquí un ejemplo de cómo puedes configurar el usuario con él:
// 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
});
