matrix-org / matrix-android-sdk
Denna SDK är föråldrad och kärnteamet arbetar inte längre med den.
Vi rekommenderar starkt att nya projekt använder den nya Android Matrix SDK.
Vi kan dock ge bästa möjliga stöd till befintliga projekt som fortfarande använder detta SDK.
matrix-android-sdk
Sdk för Android omsluter Matrix REST API-anrop i asynkrona Javametoder och tillhandahåller grundläggande strukturer för lagring och hantering av data.
Det är ett Android Studio (gradle)-projekt som innehåller SDK-modulen.https://github.com/vector-im/riot-android är exempelappen som använder den här SDK:n.
Översikt
Matrix API:erna är uppdelade i flera kategorier (se ).Grundläggande användning är:
- Logga in eller registrera dig på en hemserver -> hämta användarens autentiseringsuppgifter
- Starta en session med autentiseringsuppgifterna
- Börja lyssna på händelseströmmen
- Företag matris-API-anrop
Buggar/funktionsbegäranden
Tänker du att du har hittat ett fel? Kontrollera om det inte finns ett problem ännu, och om så inte är fallet, öppna ett problem på denna Github-repo. Om ett problem redan existerar är du välkommen att uppvotera det.
Bidra
Vill du åtgärda ett fel eller lägga till en ny funktion? Kontrollera om det finns ett motsvarande öppnat problem.Om ingen arbetar aktivt med problemet, vänligen välj develop-grenen när du skriver din lösning och öppna en pull request när du är klar. Basera inte dina pull-förfrågningar på master.
Logga in
För att logga in använder du en instans av inloggnings-API-klienten.
HomeServerConnectionConfig hsConfig = new HomeServerConnectionConfig.Builder() .withHomeServerUri(Uri.parse("https://matrix.org")) .build();new LoginRestClient(hsConfig).loginWithUser(username, password, new SimpleApiCallback<Credentials>());
Om det lyckas kommer callbacken att ge användarens inloggningsuppgifter som ska användas från och med nu.
Starta matrialsessionen
Sessionen representerar en användares session med en viss hemserver. Det kan potentiellt finnas flera sessioner för att hantera flera konton.
MXSession session = new MXSession.Builder(hsConfig, new MXDataHandler(store, credentials), getApplicationContext()) .build();
Inställer en session för att interagera med hemservern.
Sessionen ger tillgång till de olika API:erna via REST-klienterna:
session.getEventsApiClient() för API:erna för händelser
session.getProfileApiClient() för API:erna för profiler
session.getPresenceApiClient() för API:erna för närvaro
session.getRoomsApiClient() för API:erna för rum
För en fullständig lista över metoder hänvisar vi till .
ExempelAtt få listan över medlemmarna i ett chattrum skulle se ut ungefär så här:
session.getRoomsApiClient().getRoomMembers(<roomId>, callback);
Det är samma sessionsobjekt som ska användas för varje begäran. Detta kan kräva användning av en singleton, se Matrix singleton i app modulen för ett exempel.
Händelseströmmen
En viktig del av en Matrix-aktiverad app är att lyssna på händelseströmmen, det levande flödet av händelser (meddelanden, tillståndsändringar etc.).Detta görs med hjälp av:
session.startEventStream();
Detta startar händelsetråden och ställer in den för att skicka händelser till en standardlyssnare.Det kan vara användbart att använda detta tillsammans med en Android Service för att styra om händelseströmmen körs i bakgrunden eller inte.
Databehandlaren
Databehandlaren tillhandahåller ett lager för att hjälpa till att hantera data från händelseströmmen. Även om det är möjligt att skriva en app med nodata handler och manuellt göra API-anrop är det starkt rekommenderat att använda en sådan för de flesta användningsområden. Datahanteraren :
- Hanterar händelser från händelseströmmen
- Hanterar data i sitt lagringslager
- Gör det möjligt för en app att få callbacks för händelser
- Gör och upprätthåller rumsobjekt för rumsspecifika operationer (hämta meddelanden, gå med, sparka, bjuda in, osv.)
MXDataHandler dataHandler = new MXDataHandler(new MXMemoryStore());
skapar en datahanterare med standardimplementationen för lagring i minnet.
Registrera en lyssnare
För att bli informerad om händelser måste appen implementera en händelselistare.
session.getDataHandler().addListener(eventListener);
Denna lyssnare bör vara en underklass av MXEventListener och åsidosätta metoderna vid behov:
onPresenceUpdate(event, user) Triggad när en användares närvaro har uppdaterats.
onLiveEvent(event, roomState) Triggad när en live-händelse har kommit ner i händelseströmmen.
onBackEvent(event, roomState) Triggad när en gammal händelse (från historik), eller tillbaka-händelse, har returnerats efter en begäran om mer historik.
onInitialSyncComplete() Triggad när den inledande synkroniseringsprocessen har slutförts. Den första synkroniseringen är det första anropet som händelseströmmen görför att initialisera tillståndet för alla kända rum, användare osv.
Rumobjektet
Rumobjektet tillhandahåller metoder för att interagera med ett rum (hämta meddelandehistorik, gå med osv).
Room room = session.getDataHandler().getRoom(roomId);
Hämtar (eller skapar) det rumsobjekt som är kopplat till det givna rums-id:et.
Room state
RoomState-objektet representerar rummets tillstånd vid en viss tidpunkt: dess namn, ämne, synlighet (offentlig/privat), medlemmar osv. onLiveEvent och onBackEvent callbacks (se Registrera en lyssnare) returnerar händelsen, men också rummets tillstånd vid tidpunkten för händelsen för att fungera som kontext för att bygga upp visningen (t.ex. användarens visningsnamn vid tidpunkten för deras meddelande). Det tillstånd som tillhandahålls är det som gällde innan händelsen bearbetades, om händelsen råkar ändra rummets tillstånd.
Rumshistorik
När en app går in i ett rum vill den vanligtvis visa de senaste meddelandena. Detta görs genom att anropa
room.requestHistory();
Händelserna returneras sedan via onBackEvent(event, roomState) callback i omvänd ordning (senaste först).
Detta utlöser inte att hela rummets historik returneras, utan endast cirka 15 meddelanden. Genom att ringa requestHistory() igen hämtas sedan nästa (tidigare) 15 eller så, och så vidare. För att börja begära historik från det aktuella live-tillståndet (t.ex. när man öppnar eller återöppnar ett rum) måste
room.initHistory();
anropas före historikförfrågningarna.
Innehållshanteraren
Matrix-hemservrar tillhandahåller ett innehålls-API för nedladdning och uppladdning av innehåll (bilder, videoklipp, filer etc.).Innehållshanteraren tillhandahåller en omslagsform kring detta API.
session.getContentManager();
Hämtar den innehållshanterare som är associerad med den givna sessionen.
Hämtning av innehåll
Innehåll som finns på en hemserver identifieras (i händelser, URL:er för avatarer osv.) av en URI med ett mxc-schema (t.ex. mxc://matrix.org/xxxx).För att få fram den underliggande HTTP-URI:n för att hämta innehållet använder du
contentManager.getDownloadableUrl(contentUrl);
där contentUrl är mxc://-URL:n för innehållet.
För bilder finns det ytterligare en metod för att returnera miniatyrbilder i stället för bilder i full storlek:
contentManager.getDownloadableThumbnailUrl(contentUrl, width, height, method);
vilket gör det möjligt att begära en specifik bredd, höjd och skalningsmetod (mellan scale och crop).
Uppladdning av innehåll
För att ladda upp innehåll från en fil använder du
contentManager.uploadContent(filePath, callback);
som specificerar filens sökväg och en callback-metod som returnerar ett objekt när den är färdigställd och som innehåller den URI i mxc-stil där det uppladdade innehållet nu kan hittas.
Se exempelappen och Javadoc för mer information.