matrix-org / matrix-android-sdk
Tämä SDK on vanhentunut eikä ydintiimi työskentele enää sen parissa.
Suositamme lämpimästi, että uusissa projekteissa käytettäisiin Androidin uutta Matrix SDK:ta.
Voimme kuitenkin tarjota parhaan kykymme mukaan tukea olemassa oleville projekteille, jotka vielä käyttävät tätä SDK:ta.
matrix-android-sdk
Androidin SDK kietoo Matrixin REST-API-kutsut asynkronisiin Java-metodeihin ja tarjoaa perusrakenteet datan tallentamiseen ja käsittelyyn.
Se on Android Studio (gradle) -projekti, joka sisältää SDK-moduulin.https://github.com/vector-im/riot-android on esimerkkisovellus, joka käyttää tätä SDK:ta.
Yleiskatsaus
Matrixin API:t on jaettu useisiin luokkiin (ks ).Peruskäyttö on:
- Kirjaudu sisään tai rekisteröidy kotipalvelimelle ->hae käyttäjän tunnukset
- Aloita istunto tunnuksilla
- Aloita tapahtumavirran kuuntelu
- Tehdä Matrix API-kutsuja
Viat / ominaisuuspyynnöt
Epäiletkö löytäneesi virheen? Tarkista, jos issuedoes ei ole vielä olemassa, ja jos ei, avaa ongelma tähän Github-repoon. Jos issue on jo olemassa, anna sille upvote.
Contributing
Haluatko korjata bugin tai lisätä uuden ominaisuuden? Tarkista, onko olemassa vastaava avattu ongelma.Jos kukaan ei aktiivisesti työskentele ongelman parissa, siirry korjausta kirjoittaessasi develop-haaraan ja avaa pull request, kun olet valmis. Älä perusta pull-pyyntöjäsi master:n pohjalta.
Kirjautuminen sisään
Kirjautuaksesi sisään, käytä kirjautumis-API-asiakkaan instanssia.
HomeServerConnectionConfig hsConfig = new HomeServerConnectionConfig.Builder() .withHomeServerUri(Uri.parse("https://matrix.org")) .build();new LoginRestClient(hsConfig).loginWithUser(username, password, new SimpleApiCallback<Credentials>());
Jos kirjautuminen onnistuu, takaisinsoitto antaa käyttäjän tunnukset, joita käytetään tästä eteenpäin.
Matriisi-istunnon aloittaminen
Sessio edustaa yhden käyttäjän istuntoa tietyllä kotipalvelimella. Mahdollisesti voi olla useita istuntoja useiden tilien käsittelyä varten.
MXSession session = new MXSession.Builder(hsConfig, new MXDataHandler(store, credentials), getApplicationContext()) .build();
perustaa istunnon vuorovaikutusta varten kotipalvelimen kanssa.
Sessio antaa pääsyn eri API:ille REST-asiakkaiden kautta:
session.getEventsApiClient() tapahtumien API:lle
session.getProfileApiClient() profiilin API:lle
session.getPresenceApiClient() läsnäolon API:lle
session.getRoomsApiClient() huoneiden API:lle
Metodien täydellisen luettelon löydät .
EsimerkkiKeskusteluhuoneen jäsenluettelon hakeminen näyttäisi jotakuinkin tältä:
session.getRoomsApiClient().getRoomMembers(<roomId>, callback);
Kussakin pyynnössä on käytettävä samaa istuntoobjektia. Tämä saattaa vaatia singletonin käyttöä, katso Matrix singletonia app-moduulin app esimerkkiä varten.
Tapahtumavirta
Yksi tärkeäksi osaksi mitä tahansa Matrixia käyttävää sovellusta on tapahtumavirran kuuntelu, eli tapahtumien (viestien, tilanmuutosten jne.) elävä virta.Tämä tapahtuu käyttämällä:
session.startEventStream();
Tämä käynnistää tapahtumaketjun ja asettaa sen lähettämään tapahtumia oletuskuuntelijalle.Saattaa olla hyödyllistä käyttää tätä yhdessä Android Service:n kanssa, jotta voidaan kontrolloida, onko tapahtumavirta käynnissä taustalla vai ei.
Tiedonkäsittelijä
Tiedonkäsittelijä tarjoaa kerroksen, jonka avulla voidaan hallinnoida tapahtumavirrasta tulevaa tietoa. Vaikka on mahdollista kirjoittaa sovellus, jossa on nodata-käsittelijä, ja tehdä API-kutsuja manuaalisesti, datakäsittelijän käyttäminen on erittäin suositeltavaa useimmissa käyttötarkoituksissa. Datakäsittelijä :
- Käsittelee tapahtumia tapahtumavirrasta
- Tallentaa tiedot tallennuskerrokseensa
- Tarjoaa sovellukselle keinon saada takaisinkutsuja tapahtumille
- Tarjoaa ja ylläpitää huoneobjekteja huonekohtaisia operaatioita varten (viestien saaminen, liittyminen, potkiminen, kutsuminen jne.)
MXDataHandler dataHandler = new MXDataHandler(new MXMemoryStore());
luo tiedonkäsittelijän, jolla on oletusarvoisesti muistitallennuksen toteutus.
Kuuntelijan rekisteröinti
Sovelluksen on implementoitava tapahtumakuuntelija saadakseen tiedon tapahtumista.
session.getDataHandler().addListener(eventListener);
Tämän kuuntelijan tulisi olla aliluokka MXEventListener ja ohittaa metodit tarpeen mukaan:
onPresenceUpdate(event, user) Ohjattu, kun käyttäjän läsnäolo on päivitetty.
onLiveEvent(event, roomState) Ohjattu, kun tapahtumavirrassa on tullut live-tapahtuma.
onBackEvent(event, roomState) Triggeroituu, kun vanha tapahtuma (historiasta) tai takaisin tapahtuma on palautettu, kun on pyydetty lisää historiaa.
onInitialSyncComplete() Triggeroituu, kun alkuperäinen synkronointiprosessi on päättynyt. Alustava synkronointi on ensimmäinen kutsu, jonka tapahtumavirta tekee kaikkien tunnettujen huoneiden, käyttäjien jne. tilan alustamiseksi.
Huone-olio
Huone-olio tarjoaa metodeja, joilla voi olla vuorovaikutuksessa huoneen kanssa (viestihistorian hakeminen, liittyminen jne.).
Room room = session.getDataHandler().getRoom(roomId);
noutaa (tai luo) huone-olion, joka liittyy annettuun huoneen tunnukseen.
Huoneen tila
Huoneen tila -objekti edustaa huoneen tilaa tiettynä ajankohtana: sen nimeä, aihetta, näkyvyyttä (julkinen/yksityinen), jäseniä jne. onLiveEvent- ja onBackEvent-kutsupalautteet (ks. kuuntelijan rekisteröinti) palauttavat tapahtuman, mutta myös huoneen tilan tapahtumahetkellä, jotta sitä voidaan käyttää asiayhteytenä näytön rakentamisessa (esim. käyttäjän näyttönimi hänen viestinsä aikaan). Toimitettu tila on tila ennen tapahtuman käsittelyä, jos tapahtuma sattuu muuttamaan huoneen tilaa.
Huonehistoria
Sovellus haluaa yleensä näyttää viimeisimmät viestit huoneeseen tullessaan. Tämä tapahtuu kutsumalla
room.requestHistory();
Tapahtumat palautetaan onBackEvent(event, roomState)kutsun kautta käänteisessä järjestyksessä (uusimmat ensin).
Tällöin ei palauteta koko huoneen historiaa vaan vain noin 15 viestiä. Kutsumalla requestHistory() uudelleen haetaan sitten seuraavat (aikaisemmat) noin 15, ja niin edelleen. Jos haluat aloittaa historian pyytämisen nykyisestä elävästä tilasta (esim. huoneen avaamisen tai uudelleen avaamisen yhteydessä),
room.initHistory();
on kutsuttava ennen historiapyyntöjä.
Sisällönhallinta
Matrix-kotipalvelimet tarjoavat sisällön API:n sisällön (kuvien, videoiden, tiedostojen yms.) lataamista ja lataamista varten.Sisällönhallinta tarjoaa kääreen tuon API:n ympärille.
session.getContentManager();
noutaa kyseiseen istuntoon liittyvän sisällönhallinnan.
Sisällön lataaminen
Kotipalvelimen isännöimä sisältö tunnistetaan (tapahtumissa, avatar-URL-osoitteissa jne.) URI:llä, jossa on mxc-skeema (esimerkiksi mxc://matrix.org/xxxx).Jos haluat saada taustalla olevan HTTP-URI:n sisällön hakemista varten, käytä
contentManager.getDownloadableUrl(contentUrl);
, jossa contentUrl on mxc://-sisällön URL-osoite.
Kuville on olemassa lisämenetelmä, jolla voidaan palauttaa pikkukuvia täysikokoisten kuvien sijasta:
contentManager.getDownloadableThumbnailUrl(contentUrl, width, height, method);
jolla voit pyytää tiettyä leveyttä, korkeutta ja mittakaavamenetelmää (mittakaava- ja rajausmenetelmän välillä).
Sisällön lataaminen
Sisällön lataamiseen tiedostosta käytetään
contentManager.uploadContent(filePath, callback);
määrittämällä tiedostopolku ja takaisinkutsumenetelmä, joka palauttaa valmistuessaan objektin, joka sisältää mxc-tyylisen URI:n, josta ladattu sisältö nyt löytyy.
Katsokaa esimerkkisovellusta ja Javadocia saadaksenne lisätietoa.