matrix-org / matrix-android-sdk

Acest SDK este depreciat și echipa de bază nu mai lucrează la el.

Recomandăm cu tărie ca noile proiecte să folosească noul Android Matrix SDK.

Putem oferi totuși cel mai bun suport pentru proiectele existente care încă folosesc acest SDK.

matrix-android-sdk

SdK pentru Android înfășoară apelurile API Matrix REST în metode Java asincrone și oferă structuri de bază pentru stocarea și manipularea datelor.

Este un proiect Android Studio (gradle) care conține modulul SDK.https://github.com/vector-im/riot-android este aplicația de probă care utilizează acest SDK.

Prezentare generală

Aplicațiile API Matrix sunt împărțite în mai multe categorii (vezi ).Utilizarea de bază este:

1. Intrați sau înregistrați-vă pe un server de acasă -> obțineți acreditările utilizatorului
2. Începeți o sesiune cu acreditările
3. Începeți să ascultați fluxul de evenimente
4. Faceți apeluri la Matrix API

Bug-uri / Solicitări de caracteristici

Creziți că ați găsit un bug? Vă rugăm să verificați dacă nu există încă un issuedo, apoi, dacă nu, deschideți o problemă pe acest repo Github. Dacă o problemă există deja, nu ezitați să o votați.

Contribuire

Vreți să remediați un bug sau să adăugați o nouă caracteristică? Verificați dacă există o problemă deschisă corespunzătoare.Dacă nimeni nu lucrează în mod activ la problemă, atunci vă rugăm să vă îndreptați spre ramura develop atunci când scrieți soluția dvs. și deschideți o cerere de extragere când sunteți gata. Nu vă bazați cererile de tip pull request pe master.

Conectare

Pentru a vă conecta, utilizați o instanță a clientului API de conectare.

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

În caz de reușită, callback-ul va furniza acreditările de utilizator care vor fi utilizate de acum încolo.

Începerea sesiunii matricei

Sesiunea reprezintă sesiunea unui utilizator cu un anumit server de origine. Pot exista potențial mai multe sesiuni pentru gestionarea mai multor conturi.

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

setează o sesiune pentru a interacționa cu serverul de origine.

Sesiunea oferă acces la diferite API-uri prin intermediul clienților REST:

session.getEventsApiClient() pentru API de evenimente

session.getProfileApiClient() pentru API de profil

session.getPresenceApiClient() pentru API de prezență

session.getRoomsApiClient() pentru API de camere

Pentru lista completă a metodelor, vă rugăm să consultați fișierul .

ExempluObținerea listei membrilor unei săli de chat ar arăta cam așa:

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

Ar trebui să se utilizeze același obiect de sesiune pentru fiecare cerere. Acest lucru poate necesita utilizarea unui singleton, a se vedea singletonul Matrix din modulul app pentru un exemplu.

Fluxul de evenimente

O parte importantă a oricărei aplicații compatibile cu Matrix va fi ascultarea fluxului de evenimente, fluxul live de evenimente (mesaje, schimbări de stare etc.).Acest lucru se face folosind:

session.startEventStream();

Aceasta pornește firul evenimentelor și îl setează să trimită evenimentele către un ascultător implicit.Poate fi util să folosiți acest lucru împreună cu un Service Android pentru a controla dacă fluxul de evenimente rulează în fundal sau nu.

Manipulatorul de date

Manipulatorul de date oferă un strat pentru a ajuta la gestionarea datelor din fluxul de evenimente. Deși este posibil să scrieți o aplicație cu nodata handler și să efectuați manual apeluri API, utilizarea unuia este foarte recomandată pentru majoritatea utilizărilor. Manipulatorul de date :

• Gestionează evenimentele din fluxul de evenimente
• Stochează datele în stratul său de stocare
• Furnizează mijloacele prin care o aplicație poate obține callback-uri pentru evenimente
• Furnizează și întreține obiecte de cameră pentru operațiuni specifice camerei (obținerea de mesaje, aderarea, lovirea, invitarea, invitarea, etc.)

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

creează un gestionar de date cu implementarea implicită de stocare în memorie.

Înregistrarea unui ascultător

Pentru a fi informată de evenimente, aplicația trebuie să implementeze un ascultător de evenimente.

session.getDataHandler().addListener(eventListener);

Acest ascultător ar trebui să subclasă MXEventListener și să suprascrie metodele după cum este necesar:

onPresenceUpdate(event, user) Declanșat atunci când prezența unui utilizator a fost actualizată.

onLiveEvent(event, roomState) Declanșat atunci când un eveniment live a coborât în fluxul de evenimente.

onBackEvent(event, roomState) Declanșat atunci când un eveniment vechi (din istoric), sau un eveniment înapoi, a fost returnat după o cerere pentru mai mult istoric.

onInitialSyncComplete() Declanșat atunci când procesul inițial de sincronizare s-a încheiat. Sincronizarea inițială este primul apel pe care fluxul de evenimente îl facepentru a inițializa starea tuturor camerelor, utilizatorilor etc. cunoscute.

Obiectul Room

Obiectul Room oferă metode de interacțiune cu o cameră (obținerea istoricului mesajelor, aderarea etc.).

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

obține (sau creează) obiectul room asociat cu ID-ul camerei dat.

Room state

Obiectul RoomState reprezintă starea camerei la un anumit moment dat: nume, subiect, vizibilitate (public/privat), membri etc. onLiveEvent și onBackEvent callbacks (a se vedea Înregistrarea unui ascultător) returnează evenimentul, dar și starea camerei la momentul evenimentului pentru a servi drept context pentru construirea afișajului (de exemplu, numele afișat de utilizator la momentul mesajului său). Starea furnizată este cea dinaintea procesării evenimentului, dacă se întâmplă ca evenimentul să schimbe starea camerei.

Room history

Când intră într-o cameră, o aplicație dorește de obicei să afișeze ultimele mesaje. Acest lucru se face prin apelarea

room.requestHistory();

Evenimentele sunt apoi returnate prin callback-ul onBackEvent(event, roomState) în ordine inversă (mai întâi cele mai recente).

Aceasta nu declanșează returnarea întregului istoric al camerei, ci doar a aproximativ 15 mesaje. Apelarea din nou a requestHistory() va returna apoi următoarele 15 (mai devreme) sau cam așa ceva, și așa mai departe. Pentru a începe să se solicite istoricul din starea de viață curentă (de exemplu, la deschiderea sau redeschiderea unei încăperi),

room.initHistory();

trebuie să fie apelat înainte de solicitările de istoric.

Managerul de conținut

Serverele de acasă Matrix oferă un API de conținut pentru descărcarea și încărcarea de conținut (imagini, videoclipuri, fișiere etc.).Managerul de conținut oferă învelișul în jurul acelei API.

session.getContentManager();

recheamă managerul de conținut asociat cu sesiunea dată.

Descărcarea de conținut

Contenutul găzduit de un server de origine este identificat (în evenimente, URL-uri de avatar etc.) printr-un URI cu o schemă mxc (mxc://matrix.org/xxxx, de exemplu).Pentru a obține URI-ul HTTP de bază pentru recuperarea conținutului, utilizați

contentManager.getDownloadableUrl(contentUrl);

unde contentUrl este URL-ul de conținut mxc://.

Pentru imagini, există o metodă suplimentară pentru returnarea de miniaturi în loc de imagini în mărime naturală:

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

care vă permite să solicitați o lățime, o înălțime și o metodă de scalare specifice (între scale și crop).

Încărcarea de conținut

Pentru a încărca conținut dintr-un fișier, utilizați

contentManager.uploadContent(filePath, callback);

specificați calea fișierului și o metodă callback care va returna un obiect la finalizare conținând URI-ul în stil mxc unde poate fi găsit acum conținutul încărcat.

Vezi aplicația de exemplu și Javadoc-ul pentru mai multe detalii.