qiscus sdk android
v1.8.3
Qiscus Chat SDK (Software Development Kit) ist ein von Qiscus bereitgestelltes Produkt, mit dem Sie schnell und einfach eine In-App-Chat-/Chat-Funktion in Ihre Anwendungen einbetten können. Mit unserem Chat-SDK können Sie Chat-Funktionen implementieren, ohne sich mit der Komplexität der Echtzeit-Kommunikationsinfrastruktur auseinandersetzen zu müssen. Wir bieten eine leistungsstarke API, mit der Sie die Chat-Funktion im reibungslosesten Entwicklungsprozess in Ihre Apps implementieren können.
Das Qiscus Chat SDK bietet viele Funktionen wie:
Wir haben eine Beispiel-App bereitgestellt, die Ihnen das Kennenlernen unseres Chat-SDK erleichtert. Diese Beispiel-App ist mit allen Funktionen ausgestattet, sodass Sie den Ablauf und die Hauptaktivitäten mithilfe des Qiscus Chat SDK herausfinden können. Jetzt können Sie Ihre eigene Benutzeroberfläche frei anpassen. Sie können auch Ihre eigene App auf Basis unserer Beispiel-App erstellen. Für weitere Details können Sie dieses Beispiel herunterladen.
git clone https://github.com/qiscus/qiscus-chat-sdk-android-sample.git
Diese Beispiel-App verwendet eine Beispiel-APP-ID, was bedeutet, dass Sie durch die Verwendung dieser Beispiel-App die Daten mit anderen teilen. Wenn Sie es selbst versuchen möchten, können Sie die APP-ID in Ihre eigene APP-ID ändern. Sie finden Ihre APP-ID in Ihrem Dashboard. Klicken Sie hier, um auf Ihr Dashboard zuzugreifen
Zuerst müssen Sie Ihre Anwendung im Dashboard erstellen, indem Sie auf das Qiscus Chat Dashboard zugreifen. Sie können mehr als eine App-ID erstellen.
Das Qiscus Chat SDK erfordert mindestens Android API 16 (Jelly Bean). Die Integration Ihrer App in Qiscus kann in 2 (zwei) Schritten erfolgen. Zuerst müssen Sie Ihrem .gradle-Projekt eine URL-Referenz hinzufügen. Diese Referenz ist eine Anleitung für .gradle, um das Qiscus Chat SDK aus dem richtigen Repository zu beziehen. Nachfolgend erfahren Sie, wie das geht:
allprojects {
repositories {
...
maven { url "https://artifactory.qiscus.com/artifactory/qiscus-library-open-source" }
}
}
Zweitens müssen Sie SDK-Abhängigkeiten in Ihrer App .gradle hinzufügen. Anschließend müssen Sie eine Synchronisierung durchführen, um das Qiscus Chat SDK für Ihre App zu kompilieren.
dependencies {
...
implementation 'com.qiscus.sdk:chat-core:1.8.3'
}
Sie müssen Ihre APP-ID für Ihre Chat-App einrichten, bevor Sie die Authentifizierung durchführen. Diese Initialisierung muss nur einmal im App-Lebenszyklus durchgeführt werden. Die Initialisierung kann bei der Erstinbetriebnahme durchgeführt werden. So können Sie das tun:
public class SampleApp extends Application {
@ Override
public void onCreate () {
super . onCreate ();
QiscusCore . initWithAppId ( this , APPID );
}
}Die Initialisierung sollte einmalig über eine Android-App aufgerufen werden. Die beste Praxis, die Sie in den Bewerbungskurs einbauen können.
Um die Funktionen des Qiscus Chat SDK nutzen zu können, muss sich ein Benutzer beim Qiscus Server authentifizieren. Weitere Einzelheiten finden Sie im Abschnitt „Authentifizierung“. Diese Authentifizierung erfolgt durch Aufruf der Funktion setUser(). Diese Funktion ruft Benutzeranmeldeinformationen basierend auf der eindeutigen Benutzer-ID ab oder erstellt sie, zum Beispiel:
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
});Wo:
userId (Zeichenfolge, eindeutig): Eine Benutzerkennung, die zur Identifizierung eines Benutzers verwendet wird und immer dann verwendet wird, wenn ein anderer Benutzer mit diesem Benutzer chatten muss. Es kann alles sein, sei es die E-Mail-Adresse des Benutzers, der Index Ihrer Benutzerdatenbank usw. Solange es eindeutig und eine Zeichenfolge ist.
userKey (Zeichenfolge): Benutzerschlüssel für Authentifizierungszwecke. Selbst wenn ein Fremder Ihre Benutzer-ID kennt, kann er nicht auf die Benutzerdaten zugreifen.
Benutzername (Zeichenfolge): Benutzername für Anzeigenamen in Chatroom-Zwecken.
avatarURL (Zeichenfolge, optional): um den Avatar des Benutzers anzuzeigen. Falls nicht angegeben, wird auf den Standard-Avatar zurückgegriffen.
Anhand der folgenden Abbildung können Sie lernen, was wirklich passiert ist, als die Funktion setUser() aufgerufen wurde:
Nachdem Ihr Benutzerkonto erstellt wurde, müssen Sie möglicherweise manchmal Benutzerinformationen aktualisieren, z. B. den Benutzer-Avatar ändern. Mit der Methode QiscusCore.updateUser() können Sie Änderungen an Ihrem Konto vornehmen.
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
}
});Wie im vorherigen Abschnitt erwähnt, werden die Benutzerdaten bei der Ausführung von setUser() lokal gespeichert. Wenn der Benutzer die Verbindung zum Qiscus Chat SDK-Dienst trennen muss, müssen Sie die Benutzerdaten, die sich auf das Qiscus Chat SDK beziehen, wie Token, Profil, Nachrichten, Räume usw., vom lokalen Gerät löschen. Sie können dies tun, indem Sie die Methode clearUser() aufrufen:
QiscusCore . clearUser ();Der Chatraum ist ein Ort, an dem zwei oder mehr Benutzer miteinander chatten können. Es gibt drei Arten von Chatrooms, die mit dem Qiscus Chat SDK erstellt werden können: 1-zu-1-Chatroom, Gruppen-Chatroom und Kanal. In einigen Fällen kann ein Raum anhand der eindeutigen Raum-ID oder des Raumnamens identifiziert werden.
Wir gehen davon aus, dass Sie bereits einen Zielbenutzer kennen, mit dem Sie chatten möchten. Stellen Sie sicher, dass Ihr Zielbenutzer über die Methode setUser() im Qiscus Chat SDK registriert wurde, wie im vorherigen Abschnitt erläutert. Um eine Konversation mit Ihrem Zielbenutzer zu beginnen, kann dies mit der Methode getChatRoom() erfolgen. Das Qiscus Chat SDK stellt Ihnen dann asynchron einen neuen Chatraum zur Verfügung. Wenn der Raum erfolgreich erstellt wurde, gibt das Qiscus Chat SDK über onSuccess() -Listener ein Chatroom-Paket zurück.
QiscusApi . getInstance (). chatUser ( userId , options )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
// on error
});Wo:
userId : Eine Benutzerkennung, die zur Identifizierung eines Benutzers verwendet wird und immer dann verwendet wird, wenn ein anderer Benutzer mit diesem Benutzer chatten muss. Es kann alles sein, sei es die E-Mail-Adresse des Benutzers, der Index Ihrer Benutzerdatenbank usw. Solange es eindeutig und eine Zeichenfolge ist.
uniqueId : (veraltet) Sie können „ “ (leere Zeichenfolge) ausfüllen.
Optionen : Metadaten, die als zusätzliche Informationen zum Chatroom dienen können, bestehend aus Schlüsselwerten, zum Beispiel Schlüssel: Hintergrund und Wert: Rot.
Wenn Sie möchten, dass Ihre vielen Benutzer in einem 1-zu-1-Chatraum miteinander chatten, müssen Sie einen Gruppenraum erstellen. Grundsätzlich hat Group Room das gleiche Konzept wie 1-zu-1-Chatroom, der Unterschied besteht jedoch darin, dass Group Room mit einer einzigen Methode auf eine Reihe von Benutzer-IDs abzielt. So können Sie einen Gruppenraum erstellen:
QiscusApi . getInstance (). createGroupChat ( roomName , userIds , avatarUrl , options );
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
// on error
});Das Erstellen eines Kanal-Chatrooms ist ideal für einen Anwendungsfall, der eine große Teilnehmerzahl von mehr als 100 erfordert.
Sie müssen eine eindeutige ID festlegen, um einen Kanal-Chatraum zu identifizieren. Wenn kein Chatraum mit vordefinierter eindeutiger ID vorhanden ist, wird ein neuer erstellt, bei dem der Anforderer der einzige Teilnehmer ist. Andernfalls, wenn ein Chatraum mit vordefinierter eindeutiger ID bereits vorhanden ist, wird dieser Raum zurückgegeben und der Anforderer als Teilnehmer hinzugefügt.
Wenn der Raum beim ersten Aufruf nicht existiert und Sie weder avatarUrl noch roomName senden, wird der Standardwert verwendet. Aber nach dem zweiten Aufruf (Raum existiert) und Sie avatarUrl und/oder roomName senden, wird es auf diesen Wert aktualisiert. Zum Beispiel der Implementierungserstellungskanal:
QiscusApi . getInstance (). createChannel ( uniqueId , roomName , avatarUrl , options )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
// on error
});In einigen Fällen müssen Sie möglicherweise weitere Teilnehmer zu Ihrem Raumchat hinzufügen oder sogar Teilnehmer entfernen.
Um eine Liste aller Räume zu erhalten, können Sie QiscusApi.getInstance().getChatRooms(int page, int limit, boolean showMembers) aufrufen. Die Seite beginnt bei 1, der Grenzwert gibt die maximale Anzahl an Räumen pro Seite an. showMembers ist ein Flag für das Laden von Raummitgliedern oder nicht. Hier Beispielcode:
QiscusApi . getInstance (). getAllChatRooms ( showParticipant , showRemoved , showEmpty , page , limit )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRooms -> {
//on success
}, throwable -> {
//on error
});Sie können dem Chatroom mehr als einen Teilnehmer hinzufügen, indem Sie die Methode addRoomMember aufrufen. Sie können auch mehrere Benutzer-IDs übergeben. Sobald es einem Teilnehmer gelingt, dem Chatroom beizutreten, erhält er einen neuen Chatroom in seiner Chatroom-Liste.
QiscusApi . getInstance (). addParticipants ( roomId , userId )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
// on success
}, throwable -> {
//on error
});Sie können mehr als einen Teilnehmer im Chatroom entfernen, indem Sie die Methode „removeRoomMember“ aufrufen. Sie können auch mehrere Benutzer-IDs übergeben. Sobald ein Teilnehmer aus dem Chatroom entfernt wird, findet er den entsprechenden Chatroom nicht mehr in seiner Chatroom-Liste.
QiscusApi . getInstance (). removeParticipants ( roomId , userId )
. subscribeOn ( Schedulers . io ())
. observeOn ( AndroidSchedulers . mainThread ())
. subscribe ( chatRoom -> {
//success
}, throwable -> {
//error
});Installieren Sie zunächst FCM in Ihren Apps. Sie können diesen Schritten folgen. Sie können diesen Schritt überspringen, wenn Ihre Apps bereits FCM verwenden. Geben Sie dann Ihren API-Schlüssel in das Qiscus-Dashboard ein. Lassen Sie uns nun die Qiscus-Client-SDK integrieren. Aktivieren Sie zunächst FCM in der Qiscus-Chat-Konfiguration.
Qiscus . getChatConfig (). setEnableFcmPushNotification ( true );Danach müssen Sie das FCM-Token registrieren, um das Qiscus Chat SDK zu benachrichtigen. Sie können sendCurrentToken() nach der Anmeldung und auf der Startseite (war die Anmeldung in Qiscus) aufrufen, zum Beispiel:
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>
Nach der Registrierung Ihres FCM-Tokens erhalten Sie Daten vom FCM Qiscus Chat SDK, die Sie mit der Methode handleMessageReceived() verarbeiten können, zum Beispiel:
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());
}
});
}
}
Das Qiscus Chat SDK bietet eine einfache Möglichkeit, Anwendungen zu ermöglichen, einige Echtzeitereignisse zu veröffentlichen und abzuhören. Sie können Eingaben, Lesevorgänge, Benutzerstatus und benutzerdefinierte Ereignisse veröffentlichen, sodass Sie sie im Ereignishandler frei verarbeiten können. Dadurch können Sie Benutzer darüber informieren, dass ein anderer Teilnehmer aktiv mit ihnen kommuniziert.
Das Qiscus Chat SDK verwendet EventBus für die Übertragung von Ereignissen an die gesamten Anwendungen. Mehr über EventBus erfahren Sie auf dieser Website. Sie müssen lediglich das Objekt registrieren, das das Ereignis von EventBus empfangen soll. Man kann es so nennen:
EventBus . getDefault (). register ( this );Sobald Sie das Ereignis nicht mehr abhören müssen, müssen Sie die Registrierung des Empfängers aufheben, indem Sie diese Methode aufrufen:
EventBus . getDefault (). unregister ( this );Dies ist ein Beispiel für die Registrierung einer Aktivität, um ein Ereignis von EventBus zu empfangen:
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 ist der beliebteste Optimierer für Java-Bytecode. Es macht Ihre Java- und Android-Anwendungen kleiner und schneller. Weitere Informationen zu Proguard finden Sie hier. Wenn Sie Proguard in Ihrer Anwendung verwenden, stellen Sie sicher, dass Sie die Proguard-Regeln von Qiscus aus den Qiscus Proguard-Regeln zu Ihren Proguard-Regeln hinzufügen.
Für diejenigen, die lieber mit RXJava programmieren, unterstützt das Qiscus Chat SDK RXJava. Sie können also alles genauso machen wie mit Native Java. Um beispielsweise einen Benutzer festzulegen, wie im Abschnitt „Basisauthentifizierung“ erläutert, können Sie dasselbe mit RXJava tun. Hier ein Beispiel, wie Sie damit Benutzer festlegen können:
// 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
});
