matrix-org / matrix-android-sdk

Dieses SDK ist veraltet und das Kernteam arbeitet nicht mehr daran.

Wir empfehlen dringend, dass neue Projekte das neue Android Matrix SDK verwenden.

Wir können jedoch bestmöglichen Support für bestehende Projekte bieten, die dieses SDK noch verwenden.

matrix-android-sdk

Das SDK für Android wickelt die Matrix REST API-Aufrufe in asynchrone Java-Methoden ein und bietet grundlegende Strukturen zum Speichern und Verarbeiten von Daten.

Es handelt sich um ein Android Studio (gradle)-Projekt, das das SDK-Modul enthält.https://github.com/vector-im/riot-androidist die Beispiel-App, die dieses SDK verwendet.

Überblick

Die Matrix-APIs sind in mehrere Kategorien unterteilt (siehe ).Die grundsätzliche Verwendung ist:

1. Anmelden oder Registrieren bei einem Home Server ->Abrufen der Anmeldedaten des Benutzers
2. Starten einer Sitzung mit den Anmeldedaten
3. Starten des Abhörens des Ereignisstroms
4. Aufrufen der Matrix-API

Bugs / Feature Requests

Sie denken, Sie haben einen Fehler gefunden? Bitte prüfen Sie, ob ein Issue noch nicht existiert, und wenn nicht, öffnen Sie ein Issue in diesem Github Repo. Wenn ein Issue bereits existiert, kannst du es gerne hoch bewerten.

Beitragen

Wollen Sie einen Fehler beheben oder eine neue Funktion hinzufügen? Wenn niemand aktiv an dem Problem arbeitet, dann forken Sie bitte den develop-Zweig, wenn Sie Ihre Korrektur schreiben, und öffnen Sie einen Pull-Request, wenn Sie fertig sind. Basieren Sie Ihre Pull-Requests nicht auf master.

Anmelden

Um sich anzumelden, verwenden Sie eine Instanz des Login-API-Clients.

HomeServerConnectionConfig hsConfig = new HomeServerConnectionConfig.Builder() .withHomeServerUri(Uri.parse("https://matrix.org")) .build();new LoginRestClient(hsConfig).loginWithUser(username, password, new SimpleApiCallback<Credentials>());

Bei Erfolg liefert der Callback die Benutzeranmeldeinformationen, die von nun an verwendet werden sollen.

Starten der Matrixsitzung

Die Sitzung stellt die Sitzung eines Benutzers mit einem bestimmten Heimatserver dar. Es kann mehrere Sitzungen geben, um mehrere Konten zu verwalten.

MXSession session = new MXSession.Builder(hsConfig, new MXDataHandler(store, credentials), getApplicationContext()) .build();

Eine Sitzung wird für die Interaktion mit dem Heimatserver eingerichtet.

Die Sitzung ermöglicht den Zugriff auf die verschiedenen APIs über die REST-Clients:

session.getEventsApiClient() für die Ereignis-API

session.getProfileApiClient() für die Profil-API

session.getPresenceApiClient() für die Präsenz-API

session.getRoomsApiClient() für die Raum-API

Die vollständige Liste der Methoden finden Sie in der .

BeispielDie Liste der Mitglieder eines Chat-Raums zu erhalten würde etwa so aussehen:

session.getRoomsApiClient().getRoomMembers(<roomId>, callback);

Das gleiche Sitzungsobjekt sollte für jede Anfrage verwendet werden. Dies kann die Verwendung eines Singletons erfordern, siehe das Matrix Singleton im app Modul für ein Beispiel.

Der Ereignisstrom

Ein wichtiger Teil jeder Matrix-fähigen Anwendung ist das Abhören des Ereignisstroms, des Live-Flusses von Ereignissen (Nachrichten, Zustandsänderungen, etc.).Dies geschieht durch die Verwendung von:

session.startEventStream();

Dies startet den Ereignis-Thread und stellt ihn so ein, dass er Ereignisse an einen Standard-Listener sendet.

Es kann nützlich sein, dies in Verbindung mit einem Android Service zu verwenden, um zu kontrollieren, ob der Ereignisstrom im Hintergrund läuft oder nicht.

Der Daten-Handler

Der Daten-Handler bietet eine Schicht, um Daten aus dem Ereignisstrom zu verwalten. Obwohl es möglich ist, eine App mit einem Nodata-Handler zu schreiben und API-Aufrufe manuell durchzuführen, wird die Verwendung eines solchen Handlers für die meisten Anwendungen dringend empfohlen. Der Datenhandler :

• Verarbeitet Ereignisse aus dem Ereignisstrom
• Speichert die Daten in seiner Speicherschicht
• Bietet einer App die Möglichkeit, Rückrufe für Ereignisse zu erhalten
• Bietet und verwaltet Raumobjekte für raumspezifische Operationen (Nachrichten erhalten, beitreten, kicken, einladen, etc.)

MXDataHandler dataHandler = new MXDataHandler(new MXMemoryStore());

erzeugt einen Datenhandler mit der Standard-Implementierung der In-Memory-Speicherung.

Registrieren eines Listeners

Um über Ereignisse informiert zu werden, muss die App einen Event-Listener implementieren.

session.getDataHandler().addListener(eventListener);

Dieser Listener sollte eine Unterklasse MXEventListener sein und die Methoden nach Bedarf überschreiben:

onPresenceUpdate(event, user) Ausgelöst, wenn die Anwesenheit eines Benutzers aktualisiert wurde.

onLiveEvent(event, roomState) Ausgelöst, wenn ein Live-Ereignis in den Ereignisstrom gelangt ist.

onBackEvent(event, roomState) Ausgelöst, wenn ein altes Ereignis (aus der Historie) oder ein zurückliegendes Ereignis nach einer Anfrage nach mehr Historie zurückgegeben wurde.

onInitialSyncComplete() Ausgelöst, wenn der anfängliche Synchronisierungsprozess abgeschlossen ist. Die Erstsynchronisation ist der erste Aufruf des Ereignisstroms, um den Status aller bekannten Räume, Benutzer usw. zu initialisieren.

Das Raumobjekt

Das Raumobjekt bietet Methoden, um mit einem Raum zu interagieren (Abrufen des Nachrichtenverlaufs, Beitreten usw.).

Room room = session.getDataHandler().getRoom(roomId);

Erhält (oder erstellt) das Raumobjekt, das mit der angegebenen Raum-ID verbunden ist.

Raumzustand

Das RoomState Objekt repräsentiert den Zustand des Raums zu einem bestimmten Zeitpunkt: Name, Thema, Sichtbarkeit (öffentlich/privat), Mitglieder, etc.onLiveEvent und onBackEvent Callbacks (siehe Registrierung eines Listeners) geben das Ereignis zurück, aber auch den Zustand des Raums zum Zeitpunkt des Ereignisses, um als Kontext für die Erstellung der Anzeige zu dienen (z.B. der Anzeigename des Benutzers zum Zeitpunkt seiner Nachricht). Der angegebene Zustand ist der vor der Verarbeitung des Ereignisses, wenn das Ereignis den Zustand des Raumes ändert.

Raumhistorie

Beim Betreten eines Raumes möchte eine App normalerweise die letzten Nachrichten anzeigen. Dies geschieht durch den Aufruf von

room.requestHistory();

Die Ereignisse werden dann durch den onBackEvent(event, roomState) Callback in umgekehrter Reihenfolge (die neuesten zuerst) zurückgegeben.

Dadurch wird nicht die gesamte Historie des Raums zurückgegeben, sondern nur etwa 15 Nachrichten. Ein erneuter Aufruf von requestHistory() ruft dann die nächsten (früheren) 15 Nachrichten ab, und so weiter. Um mit der Abfrage der Historie aus dem aktuellen Live-Zustand heraus zu beginnen (z.B. beim Öffnen oder Wiederöffnen eines Raumes),

room.initHistory();

muss vor der Abfrage der Historie aufgerufen werden.

Der Content Manager

Matrix-Home-Server bieten eine Content-API für das Herunter- und Hochladen von Inhalten (Bilder, Videos, Dateien, etc.).Der Content Manager stellt den Wrapper um diese API bereit.

session.getContentManager();

Ruft den Content Manager ab, der mit der gegebenen Sitzung verbunden ist.

Herunterladen von Inhalten

Inhalte, die von einem Home Server gehostet werden, werden (in Ereignissen, Avatar-URLs usw.) durch eine URI mit einem mxc-Schema identifiziert (z. B. mxc://matrix.org/xxxx).Um die zugrundeliegende HTTP-URI für den Abruf des Inhalts zu erhalten, verwenden Sie

contentManager.getDownloadableUrl(contentUrl);

wobei contentUrl die mxc:// content-URL ist.

Für Bilder gibt es eine zusätzliche Methode für die Rückgabe von Thumbnails anstelle von Bildern in voller Größe:

contentManager.getDownloadableThumbnailUrl(contentUrl, width, height, method);

womit Sie eine bestimmte Breite, Höhe und Skalierungsmethode (zwischen Skalierung und Zuschneiden) anfordern können.

Hochladen von Inhalten

Um Inhalte aus einer Datei hochzuladen, verwenden Sie

contentManager.uploadContent(filePath, callback);

die Angabe des Dateipfads und eine Callback-Methode, die bei Fertigstellung ein Objekt zurückgibt, das den mxc-style URI enthält, in dem der hochgeladene Inhalt nun zu finden ist.

Siehe die Beispielanwendung und Javadoc für weitere Details.