matrix-org / matrix-android-sdk
Questo SDK è deprecato e il core team non lavora più su di esso.
Si raccomanda fortemente che i nuovi progetti usino il nuovo Android Matrix SDK.
Possiamo però fornire il supporto migliore per i progetti esistenti che stanno ancora usando questo SDK.
matrix-android-sdk
L’SDK per Android avvolge le chiamate REST API di Matrix in metodi Java asincroni e fornisce strutture di base per la memorizzazione e la gestione dei dati.
È un progetto Android Studio (gradle) che contiene il modulo SDK.https://github.com/vector-im/riot-androidè l’applicazione di esempio che usa questo SDK.
Panoramica
Le API di Matrix sono divise in diverse categorie (vedi ).L’uso di base è:
- Entrare o registrarsi ad un server domestico -> ottenere le credenziali dell’utente
- Avviare una sessione con le credenziali
- Avviare l’ascolto del flusso di eventi
- Effettuare chiamate API di matrice
Bugs / Feature Requests
Pensi di aver trovato un bug? Per favore controlla se un problema non esiste ancora, poi, se no, apri un problema su questo repo Github. Se un problema esiste già, sentiti libero di dare un voto più alto.
Contribuire
Vuoi risolvere un bug o aggiungere una nuova funzionalità? Controlla se c’è un problema aperto corrispondente; se nessuno sta lavorando attivamente al problema, allora per favore seleziona il ramo develop quando scrivi la tua correzione e apri una richiesta di pull quando sei pronto. Non basare le tue richieste di pull su master.
Accedere
Per accedere, usa un’istanza del client API di login.
HomeServerConnectionConfig hsConfig = new HomeServerConnectionConfig.Builder() .withHomeServerUri(Uri.parse("https://matrix.org")) .build();new LoginRestClient(hsConfig).loginWithUser(username, password, new SimpleApiCallback<Credentials>());
In caso di successo, il callback fornirà le credenziali utente da usare da quel momento in poi.
Avviare la sessione matrix
La sessione rappresenta la sessione di un utente con un particolare home server. Ci possono essere potenzialmente più sessioni per gestire più account.
MXSession session = new MXSession.Builder(hsConfig, new MXDataHandler(store, credentials), getApplicationContext()) .build();
Imposta una sessione per interagire con l’home server.
La sessione dà accesso alle diverse API attraverso i client REST:
session.getEventsApiClient() per l’API degli eventi
session.getProfileApiClient() per l’API del profilo
session.getPresenceApiClient() per l’API della presenza
session.getRoomsApiClient() per l’API delle stanze
Per la lista completa dei metodi, consultare il file .
Esempio: ottenere la lista dei membri di una stanza di chat sarebbe qualcosa del genere:
session.getRoomsApiClient().getRoomMembers(<roomId>, callback);
Lo stesso oggetto di sessione dovrebbe essere usato per ogni richiesta. Questo può richiedere l’uso di un singleton, vedi il singleton Matrix nel modulo app per un esempio.
Il flusso di eventi
Una parte importante di ogni app abilitata a Matrix sarà l’ascolto del flusso di eventi, il flusso in diretta di eventi (messaggi, cambiamenti di stato, ecc.).Questo viene fatto usando:
session.startEventStream();
Questo avvia il thread degli eventi e lo imposta per inviare gli eventi ad un ascoltatore predefinito.Può essere utile usarlo insieme ad un Service Android per controllare se il flusso degli eventi è in esecuzione in background o meno.
Il gestore dei dati
Il gestore dei dati fornisce un livello per aiutare a gestire i dati dal flusso degli eventi. Mentre è possibile scrivere un’applicazione con un gestore di dati e fare manualmente chiamate API, usarne uno è altamente raccomandato per la maggior parte degli usi. Il gestore di dati :
- Gestisce gli eventi dal flusso di eventi
- Memorizza i dati nel suo strato di memorizzazione
- Fornisce i mezzi per un’applicazione per ottenere callback per gli eventi
- Fornisce e mantiene oggetti stanza per operazioni specifiche della stanza (ottenere messaggi, unirsi, calciare, invitare, ecc.)
MXDataHandler dataHandler = new MXDataHandler(new MXMemoryStore());
crea un gestore di dati con l’implementazione predefinita della memorizzazione in memoria.
Registra un ascoltatore
Per essere informato sugli eventi, l’applicazione deve implementare un ascoltatore di eventi.
session.getDataHandler().addListener(eventListener);
Questo ascoltatore dovrebbe sottoclasse MXEventListener e sovrascrivere i metodi come necessario:
onPresenceUpdate(event, user) Avviato quando la presenza di un utente è stata aggiornata.
onLiveEvent(event, roomState) Avviato quando un evento live è arrivato nel flusso degli eventi.
onBackEvent(event, roomState) Si attiva quando un vecchio evento (dalla cronologia), o un evento posteriore, è stato restituito dopo una richiesta di più cronologia.
onInitialSyncComplete() Si attiva quando il processo di sincronizzazione iniziale è completato. La sincronizzazione iniziale è la prima chiamata che il flusso di eventi fa per inizializzare lo stato di tutte le stanze conosciute, gli utenti, ecc.
L’oggetto Room
L’oggetto Room fornisce metodi per interagire con una stanza (ottenere la cronologia dei messaggi, unirsi, ecc.).
Room room = session.getDataHandler().getRoom(roomId);
Prende (o crea) l’oggetto room associato al dato ID della stanza.
Stato della stanza
L’oggetto RoomState rappresenta lo stato della stanza in un certo momento: il suo nome, l’argomento, la visibilità (pubblica/privata), i membri, ecc.Le callback onLiveEvent e onBackEvent (vedi Registrazione di un ascoltatore) restituiscono l’evento, ma anche lo stato della stanza al momento dell’evento che serve da contesto per costruire la visualizzazione (ad esempio il nome dell’utente al momento del suo messaggio). Lo stato fornito è quello prima dell’elaborazione dell’evento, se l’evento cambia lo stato della stanza.
Storia della stanza
Quando si entra in una stanza, un’applicazione di solito vuole visualizzare gli ultimi messaggi. Questo viene fatto chiamando
room.requestHistory();
Gli eventi vengono poi restituiti attraverso il callback onBackEvent(event, roomState) in ordine inverso (prima i più recenti).
Questo non fa sì che tutta la storia della stanza venga restituita, ma solo circa 15 messaggi. Chiamando di nuovo requestHistory() verranno recuperati i successivi (precedenti) 15 circa, e così via. Per iniziare a richiedere la cronologia dallo stato attuale (ad esempio quando si apre o si riapre una stanza),
room.initHistory();
deve essere chiamato prima delle richieste di cronologia.
Il gestore dei contenuti
I server di casa Matrix forniscono un’API per il download e il caricamento di contenuti (immagini, video, file, ecc.).Il content manager fornisce il wrapper attorno a tale API.
session.getContentManager();
recupera il content manager associato alla sessione data.
Scaricare contenuti
I contenuti ospitati da un home server sono identificati (negli eventi, negli URL degli avatar, ecc.) da un URI con uno schema mxc (mxc://matrix.org/xxxx per esempio).Per ottenere l’URI HTTP sottostante per recuperare il contenuto, usa
contentManager.getDownloadableUrl(contentUrl);
dove contentUrl è l’URL mxc:// content.
Per le immagini, esiste un metodo aggiuntivo per restituire miniature invece di immagini a grandezza naturale:
contentManager.getDownloadableThumbnailUrl(contentUrl, width, height, method);
che permette di richiedere una specifica larghezza, altezza e metodo di scala (tra scale e crop).
Caricamento di contenuti
Per caricare contenuti da un file, usare
contentManager.uploadContent(filePath, callback);
specificando il percorso del file e un metodo di callback che restituirà un oggetto al termine contenente l’URI in stile mxc dove il contenuto caricato può ora essere trovato.
Vedi l’app di esempio e il Javadoc per maggiori dettagli.