matrix-org / matrix-android-sdk
Dette SDK er forældet, og kerneholdet arbejder ikke længere på det.
Vi anbefaler kraftigt, at nye projekter bruger det nye Android Matrix SDK.
Vi kan dog yde bedst mulig støtte til eksisterende projekter, der stadig bruger dette SDK.
matrix-android-sdk
SdK’et til Android omslutter Matrix REST API-opkald i asynkrone Java-metoder og giver grundlæggende strukturer til lagring og håndtering af data.
Det er et Android Studio (gradle)-projekt, der indeholder SDK-modulet.https://github.com/vector-im/riot-android er den prøveapp, der bruger dette SDK.
Oversigt
Matrix-API’erne er opdelt i flere kategorier (se ).Den grundlæggende brug er:
- Log ind eller registrer dig på en hjemmeserver -> få brugerens legitimationsoplysninger
- Start en session med legitimationsoplysningerne
- Start lytning til hændelsesstrømmen
- Før matrix-API-opkald
Fejl / anmodninger om funktioner
Mener du, at du har fundet en fejl? Kontroller venligst, om der ikke findes en issuedoes endnu, og hvis ikke, så åbn et problem på denne Github repo. Hvis et problem allerede eksisterer, er du velkommen til at upvote for det.
Bidrage
Vil du rette en fejl eller tilføje en ny funktion? Tjek, om der er et tilsvarende åbent problem.Hvis ingen arbejder aktivt på problemet, skal du vælge develop-grenen, når du skriver din rettelse, og åbne en pull request, når du er klar. Baser ikke dine pull-forespørgsler på master.
Log ind
For at logge ind skal du bruge en instans af login API-klienten.
HomeServerConnectionConfig hsConfig = new HomeServerConnectionConfig.Builder() .withHomeServerUri(Uri.parse("https://matrix.org")) .build();new LoginRestClient(hsConfig).loginWithUser(username, password, new SimpleApiCallback<Credentials>());
Hvis det lykkes, vil callbacken give de brugeroplysninger, der skal bruges fra nu af.
Start af matrixsession
Sessionen repræsenterer en brugers session med en bestemt hjemmeserver. Der kan potentielt være flere sessioner til håndtering af flere konti.
MXSession session = new MXSession.Builder(hsConfig, new MXDataHandler(store, credentials), getApplicationContext()) .build();
Opretter en session til at interagere med hjemmeserveren.
Sessionen giver adgang til de forskellige API’er via REST-klienterne:
session.getEventsApiClient() for hændelses-API’en
session.getProfileApiClient() for profil-API’en
session.getPresenceApiClient() for tilstedeværelses-API’en
session.getRoomsApiClient() for rum-API’en
For den komplette liste over metoder henvises til .
EksempelHentning af listen over medlemmer af et chatrum ville se nogenlunde sådan ud:
session.getRoomsApiClient().getRoomMembers(<roomId>, callback);
Det samme sessionsobjekt skal bruges til hver anmodning. Dette kan kræve brug af en singleton, se Matrix singleton i app modulet for et eksempel.
Hændelsesstrømmen
En vigtig del af enhver Matrix-aktiveret app vil være at lytte til hændelsesstrømmen, den levende strøm af begivenheder (meddelelser, tilstandsændringer osv.).Dette gøres ved hjælp af:
session.startEventStream();
Dette starter hændelsestråden og indstiller den til at sende hændelser til en standardlytter.Det kan være nyttigt at bruge dette sammen med en Android Service til at styre, om hændelsesstrømmen kører i baggrunden eller ej.
Datahåndteringen
Datahåndteringen giver et lag, der hjælper med at håndtere data fra hændelsesstrømmen. Selv om det er muligt at skrive en app med nodata-handler og manuelt foretage API-opkald, anbefales det stærkt at bruge en sådan til de fleste anvendelser. Databehandleren :
- Håndterer hændelser fra hændelsesstrømmen
- Lagerer dataene i sit lagringslag
- Giver en app mulighed for at få callbacks for hændelser
- Giver og vedligeholder rumobjekter til rumspecifikke operationer (få meddelelser, deltage, sparke, invitere osv.)
MXDataHandler dataHandler = new MXDataHandler(new MXMemoryStore());
skaber en datahåndtering med standardimplementeringen af in-memory storage.
Registrering af en lytter
For at blive informeret om begivenheder skal appen implementere en hændelseslytter.
session.getDataHandler().addListener(eventListener);
Denne lytter bør underklasses MXEventListener og overskrive metoderne efter behov:
onPresenceUpdate(event, user) Triggeres, når en brugers tilstedeværelse er blevet opdateret.
onLiveEvent(event, roomState) Triggeres, når en livehændelse er kommet ned i hændelsesstrømmen.
onBackEvent(event, roomState) Triggeres, når en gammel begivenhed (fra historikken) eller en tilbagevendende begivenhed er blevet returneret efter en anmodning om mere historik.
onInitialSyncComplete() Triggeres, når den indledende synkroniseringsproces er afsluttet. Den indledende synkronisering er det første kald, som hændelsesstrømmen foretager for at initialisere tilstanden for alle kendte rum, brugere osv.
Rumobjektet
Rumobjektet indeholder metoder til at interagere med et rum (hente beskedhistorik, tilslutte sig osv.).
Room room = session.getDataHandler().getRoom(roomId);
Henter (eller opretter) rumobjektet, der er knyttet til det givne rum-ID.
Room state
RoomState-objektet repræsenterer rummets tilstand på et bestemt tidspunkt: dets navn, emne, synlighed (offentlig/privat), medlemmer osv. onLiveEvent og onBackEvent callbacks (se Registrering af en lytter) returnerer hændelsen, men også rummets tilstand på tidspunktet for hændelsen for at tjene som kontekst for opbygning af visningen (f.eks. brugerens visningsnavn på tidspunktet for deres besked). Den tilstand, der leveres, er den tilstand, der var før behandlingen af hændelsen, hvis hændelsen tilfældigvis ændrer rummets tilstand.
Rumhistorik
Når man går ind i et rum, ønsker en app normalt at vise de seneste meddelelser. Dette gøres ved at kalde
room.requestHistory();
Hændelserne returneres derefter via onBackEvent(event, roomState) callback i omvendt rækkefølge (den seneste først).
Dette udløser ikke, at hele rummets historik returneres, men kun ca. 15 meddelelser. Ved at kalde requestHistory() igen hentes derefter de næste (tidligere) 15 eller deromkring, og så videre. For at begynde at anmode om historik fra den aktuelle livetilstand (f.eks. ved åbning eller genåbning af et rum) skal
room.initHistory();
kaldes før historikanmodningerne.
Indholdsadministrator
Matrix-hjemmeservere tilbyder en indholds-API til downloading og upload af indhold (billeder, videoer, filer osv.).Indholdsforvalteren leverer indpakningen omkring denne API.
session.getContentManager();
henter den indholdsforvalter, der er tilknyttet den givne session.
Download af indhold
Indhold, der er hostet af en hjemmeserver, identificeres (i begivenheder, avatar-URL’er osv.) ved en URI med et mxc-schema (f.eks. mxc://matrix.org/xxxx).For at få den underliggende HTTP-URI til hentning af indholdet skal du bruge
contentManager.getDownloadableUrl(contentUrl);
hvor contentUrl er mxc://-URL’en for indhold.
For billeder findes der en ekstra metode til returnering af miniaturebilleder i stedet for billeder i fuld størrelse:
contentManager.getDownloadableThumbnailUrl(contentUrl, width, height, method);
som giver dig mulighed for at anmode om en specifik bredde, højde og skaleringsmetode (mellem scale og crop).
Opload af indhold
For at uploade indhold fra en fil, skal du bruge
contentManager.uploadContent(filePath, callback);
som angiver filens sti og en callback-metode, som returnerer et objekt ved afslutning, der indeholder den mxc-style URI, hvor det uploadede indhold nu kan findes.
Se prøveappen og Javadoc for flere detaljer.