qiscus sdk android
v1.8.3
Qiscus Chat SDK (Software Development Kit) est un produit fourni par Qiscus qui vous permet d'intégrer rapidement et facilement une fonctionnalité de chat/chat dans vos applications. Avec notre SDK de chat, vous pouvez implémenter la fonctionnalité de chat sans vous soucier de la complexité de l'infrastructure de communication en temps réel. Nous fournissons une API puissante pour vous permettre d'implémenter la fonctionnalité de chat dans vos applications dans le processus de développement le plus transparent.
Qiscus Chat SDK fournit de nombreuses fonctionnalités telles que :
Nous avons fourni un exemple d'application pour vous aider à vous familiariser avec notre SDK de chat. Cet exemple d'application est construit avec des fonctionnalités complètes afin que vous puissiez comprendre le flux et les principales activités à l'aide du SDK Qiscus Chat. Vous pouvez désormais personnaliser librement votre propre interface utilisateur. Vous pouvez également créer votre propre application en plus de notre exemple d'application. Pour plus de détails, vous pouvez télécharger cet exemple.
git clone https://github.com/qiscus/qiscus-chat-sdk-android-sample.git
Cet exemple d'application utilise un exemple d'ID d'application, ce qui signifie qu'en utilisant cet exemple d'application, vous partagerez les données avec d'autres. Si vous souhaitez essayer par vous-même, vous pouvez remplacer l'ID APP par votre propre ID APP. Vous pouvez trouver votre ID APP dans votre tableau de bord. Cliquez ici pour accéder à votre tableau de bord
Tout d’abord, vous devez créer votre application dans le tableau de bord, en accédant au tableau de bord Qiscus Chat. Vous pouvez créer plusieurs ID d'application.
Le SDK Qiscus Chat nécessite au minimum l'API Android 16 (Jelly Bean). Pour intégrer votre application à Qiscus, cela peut se faire en 2 (deux) étapes. Tout d'abord, vous devez ajouter une référence URL dans votre projet .gradle. Cette référence est un guide permettant à .gradle d'obtenir le SDK Qiscus Chat à partir du bon référentiel. Voici comment procéder :
allprojects {
repositories {
...
maven { url "https://artifactory.qiscus.com/artifactory/qiscus-library-open-source" }
}
}
Deuxièmement, vous devez ajouter des dépendances du SDK dans votre application .gradle. Ensuite, vous devez synchroniser pour compiler le SDK Qiscus Chat pour votre application.
dependencies {
...
implementation 'com.qiscus.sdk:chat-core:1.8.3'
}
Vous devez initialiser votre ID APP pour votre application de chat avant de procéder à l'authentification. Cette initialisation ne doit être effectuée qu'une seule fois dans le cycle de vie de l'application. L'initialisation peut être implémentée lors du démarrage initial. Voici comment procéder :
public class SampleApp extends Application {
@ Override
public void onCreate () {
super . onCreate ();
QiscusCore . initWithAppId ( this , APPID );
}
}L'initialisation doit être appelée une fois dans une application Android. La meilleure pratique que vous pouvez mettre en classe d’application.
Pour utiliser les fonctionnalités du SDK Qiscus Chat, un utilisateur doit s'authentifier auprès du serveur Qiscus. Pour plus de détails, vous pouvez consulter la section Authentification. Cette authentification se fait en appelant la fonction setUser(). Cette fonction récupérera ou créera des informations d'identification utilisateur basées sur l'ID utilisateur unique, par exemple :
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
});Où:
userId (string, unique) : Un identifiant d'utilisateur qui sera utilisé pour identifier un utilisateur et utilisé chaque fois qu'un autre utilisateur aura besoin de discuter avec cet utilisateur. Cela peut être n'importe quoi, qu'il s'agisse de l'e-mail de l'utilisateur, de l'index de votre base de données utilisateur, etc. Tant qu'il est unique et qu'il s'agit d'une chaîne.
userKey (string) : userKey à des fins d'authentification, donc même si un inconnu connaît votre identifiant utilisateur, il ne peut pas accéder aux données utilisateur.
nom d'utilisateur (chaîne) : nom d'utilisateur pour le nom d'affichage à des fins de salon de discussion.
avatarURL (chaîne, facultatif) : pour afficher l'avatar de l'utilisateur, revenez à l'avatar par défaut s'il n'est pas fourni.
Vous pouvez apprendre de la figure ci-dessous pour comprendre ce qui s'est réellement passé lors de l'appel de la fonction setUser() :
Une fois votre compte utilisateur créé, vous devrez parfois mettre à jour les informations d'un utilisateur, par exemple en modifiant son avatar. Vous pouvez utiliser la méthode QiscusCore.updateUser() pour apporter des modifications à votre compte.
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
}
});Comme mentionné dans la section précédente, lorsque vous avez exécuté setUser(), les données de l'utilisateur seront stockées localement. Lorsque l'utilisateur doit se déconnecter du service Qiscus Chat SDK, vous devez effacer les données utilisateur liées au Qiscus Chat SDK, telles que le jeton, le profil, les messages, les salles, etc., de l'appareil local. Vous pouvez le faire en appelant la méthode clearUser() :
QiscusCore . clearUser ();Le Chat Room est un endroit où 2 utilisateurs ou plus peuvent discuter entre eux. Il existe 3 types de salles de discussion qui peuvent être créées à l'aide du SDK Qiscus Chat : salle de discussion individuelle, salle de discussion de groupe et chaîne. Dans certains cas, une pièce peut être identifiée par son identifiant unique ou son nom.
Nous supposons que vous connaissez déjà un utilisateur ciblé avec lequel vous souhaitez discuter. Assurez-vous que votre utilisateur ciblé a été enregistré dans le SDK Qiscus Chat via la méthode setUser(), comme expliqué dans la section précédente. Pour démarrer une conversation avec votre utilisateur ciblé, cela peut être fait avec la méthode getChatRoom() . Qiscus Chat SDK vous proposera alors une nouvelle salle de discussion, de manière asynchrone. Une fois la salle créée avec succès, le SDK Qiscus Chat renverra un package Chat Room via l'écouteur onSuccess() .
QiscusApi . getInstance (). chatUser ( userId , options )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
// on error
});Où:
userId : Un identifiant d'utilisateur qui sera utilisé pour identifier un utilisateur et utilisé chaque fois qu'un autre utilisateur aura besoin de discuter avec cet utilisateur. Cela peut être n'importe quoi, qu'il s'agisse de l'e-mail de l'utilisateur, de l'index de votre base de données utilisateur, etc. À condition qu'il soit unique et qu'il s'agisse d'une chaîne.
distinctId : (obsolète) vous pouvez remplir « » (chaîne vide).
options : métadonnées qui peuvent servir d'informations supplémentaires au salon de discussion, qui sont constituées d'une clé-valeur, par exemple, clé : arrière-plan et valeur : rouge.
Lorsque vous souhaitez que vos nombreux utilisateurs discutent ensemble dans une salle de discussion en tête-à-tête, vous devez créer une salle de groupe. Fondamentalement, Group Room a le même concept que 1-on-1 Chat Room, mais la différence est que Group Room ciblera un tableau d'ID utilisateur dans une seule méthode. Voici comment créer une salle de groupe :
QiscusApi . getInstance (). createGroupChat ( roomName , userIds , avatarUrl , options );
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
// on error
});La création d'une salle de discussion de chaîne est idéale pour un cas d'utilisation qui nécessite un grand nombre de participants, plus de 100.
Vous devez définir uniqueId pour identifier une salle de discussion de chaîne. Si une salle de discussion avec un identifiant unique prédéfini n'existe pas, elle en créera une nouvelle avec le demandeur comme seul participant. Sinon, si une salle de discussion avec un identifiant unique prédéfini existe déjà, elle renverra cette salle et ajoutera le demandeur en tant que participant.
Lorsque la salle n'existe pas au tout premier appel et que vous n'envoyez pas avatarUrl et/ou roomName, elle utilisera la valeur par défaut. Mais, après le deuxième appel (la salle existe) et que vous envoyez avatarUrl et/ou roomName, il sera mis à jour avec cette valeur. Par exemple, le canal de création d'implémentation :
QiscusApi . getInstance (). createChannel ( uniqueId , roomName , avatarUrl , options )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
// on error
});Dans certains cas, vous devrez peut-être ajouter des participants supplémentaires à votre discussion en salle ou même supprimer un participant.
Pour obtenir la liste de toutes les salles, vous pouvez appeler QiscusApi.getInstance().getChatRooms(int page, int limit, boolean showMembers), la page démarre à partir de 1, la limite indique le nombre maximum de salles par page, showMembers est un indicateur pour les membres de la salle de chargement également ou non. Voici un exemple de code :
QiscusApi . getInstance (). getAllChatRooms ( showParticipant , showRemoved , showEmpty , page , limit )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRooms -> {
//on success
}, throwable -> {
//on error
});Vous pouvez ajouter plusieurs participants dans Chat Room en appelant la méthode addRoomMember. Vous pouvez également transmettre plusieurs identifiants utilisateur. Une fois qu'un participant réussit à rejoindre le salon de discussion, il obtiendra un nouveau salon de discussion dans sa liste de salons de discussion.
QiscusApi . getInstance (). addParticipants ( roomId , userId )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
//on error
});Vous pouvez supprimer plusieurs participants dans Chat Room en appelant la méthode RemoveRoomMember. Vous pouvez également transmettre plusieurs ID utilisateur. Une fois qu'un participant est supprimé du salon de discussion, il ne trouvera pas le salon de discussion associé dans sa liste de salons de discussion.
QiscusApi . getInstance (). removeParticipants ( roomId , userId )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
//success
}, throwable -> {
//error
});Installez d'abord FCM sur vos applications, vous pouvez suivre ces étapes. Vous pouvez ignorer cette étape si vos applications utilisent déjà FCM. Ensuite, placez votre clé API sur le tableau de bord qiscus. Intégrons maintenant le SDK du client Qiscus, activez d'abord FCM dans la configuration du chat Qiscus.
Qiscus . getChatConfig (). setEnableFcmPushNotification ( true );Après cela, vous devez enregistrer le jeton FCM pour informer le SDK Qiscus Chat, vous pouvez appeler sendCurrentToken() après la connexion et sur la page d'accueil (c'était la connexion dans qiscus), par exemple :
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>
Après avoir enregistré votre jeton FCM, vous obtiendrez des données du SDK FCM Qiscus Chat, que vous pourrez gérer en utilisant la méthode handleMessageReceived() , par exemple :
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 fournit un moyen simple de permettre aux applications de publier et d'écouter certains événements en temps réel. Vous pouvez publier la saisie, la lecture, le statut de l'utilisateur et l'événement personnalisé afin que vous puissiez les gérer librement dans le gestionnaire d'événements. Cela vous permet d'informer les utilisateurs qu'un autre participant participe activement à communiquer avec eux.
Qiscus Chat SDK utilise EventBus pour diffuser des événements à l'ensemble des applications. Vous pouvez en savoir plus sur EventBus sur ce site Web. Ce que vous devez faire est d'enregistrer l'objet qui recevra l'événement d'EventBus. Vous pouvez l'appeler ainsi :
EventBus . getDefault (). register ( this );Une fois que vous n'avez plus besoin d'écouter l'événement, vous devez désinscrire le récepteur en appelant cette méthode :
EventBus . getDefault (). unregister ( this );Voici un exemple sur la façon d'enregistrer une activité pour recevoir un événement d'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 est l'optimiseur le plus populaire pour le bytecode Java. Cela rend vos applications Java et Android plus petites et plus rapides. Lisez ici pour plus de détails sur Proguard. Si vous utilisez Proguard dans votre application, assurez-vous d'ajouter les règles Proguard de Qiscus de Qiscus Proguard Rules à vos règles Proguard.
Pour vous qui préférez coder avec RXJava, Qiscus Chat SDK prend en charge RXJava. Ainsi, vous pouvez tout faire comme avec Native Java. Par exemple, pour définir un utilisateur, comme cela a été expliqué dans la section Authentification de base, vous pouvez faire de même avec RXJava. Voici un exemple de la façon dont vous pouvez définir un utilisateur avec :
// 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
});
