matrix-org / matrix-android-sdk

Deze SDK is deprecated en het kernteam werkt er niet meer aan.

We raden ten sterkste aan dat nieuwe projecten de nieuwe Android Matrix SDK gebruiken.

We kunnen echter wel best effort support leveren voor bestaande projecten die deze SDK nog gebruiken.

matrix-android-sdk

De SDK voor Android verpakt de Matrix REST API calls in asynchrone Java methods en biedt basisstructuren voor het opslaan en afhandelen van data.

Het is een Android Studio (gradle) project dat de SDK module bevat.https://github.com/vector-im/riot-android is de voorbeeld app die gebruik maakt van deze SDK.

Overzicht

De Matrix API’s zijn onderverdeeld in verschillende categorieën (zie ).Het basisgebruik is:

1. Inloggen of registreren op een thuisserver -> de gebruikersgegevens ophalen
2. Een sessie starten met de gebruikersgegevens
3. Luisteren naar de event stream
4. Maken van Matrix API aanroepen

Bugs / Feature Requests

Denk je een bug gevonden te hebben? Controleer of er nog geen issue bestaat, en zo niet, open dan een issue op deze Github repo. Als een issue al bestaat, voel je vrij om er een upvote voor te geven.

Bijdragen

Wilt u een bug oplossen of een nieuwe functie toevoegen? Als er niemand actief aan het probleem werkt, kies dan de develop branch wanneer u uw oplossing schrijft, en open een pull request wanneer u klaar bent. Baseer uw pull requests niet op master.

Inloggen

Om in te loggen, gebruikt u een instantie van de login API client.

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

Als het lukt, geeft de callback de gebruikersgegevens om vanaf dat moment te gebruiken.

De matrix sessie starten

De sessie vertegenwoordigt de sessie van één gebruiker met een bepaalde thuisserver. Er kunnen meerdere sessies zijn om met meerdere accounts te werken.

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

Stelt een sessie in voor interactie met de thuisserver.

De sessie geeft toegang tot de verschillende API’s via de REST-clients:

session.getEventsApiClient() voor de gebeurtenissen-API

session.getProfileApiClient() voor de profiel-API

session.getPresenceApiClient() voor de aanwezigheids-API

session.getRoomsApiClient() voor de kamers-API

Voor de volledige lijst van methoden, raadpleeg de .

VoorbeeldHet opvragen van de lijst met leden van een chatroom zou er ongeveer zo uitzien:

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

Hetzelfde sessie-object moet voor elk verzoek worden gebruikt. Dit kan het gebruik van een singleton vereisen, zie de Matrix singleton in de app module voor een voorbeeld.

De event stream

Een belangrijk onderdeel van elke app die Matrix ondersteunt is het luisteren naar de event stream, de live stroom van gebeurtenissen (berichten, toestandsveranderingen, etc.).Dit wordt gedaan door gebruik te maken van:

session.startEventStream();

Dit start de gebeurtenissen-thread en stelt deze in om gebeurtenissen naar een standaard luisteraar te sturen.Het kan nuttig zijn om dit te gebruiken in combinatie met een Android Service om te regelen of de gebeurtenissenstroom op de achtergrond draait of niet.

De datahandler

De datahandler biedt een laag om te helpen bij het beheren van gegevens uit de gebeurtenissenstroom. Hoewel het mogelijk is om een app met nodata handler te schrijven en handmatig API calls te maken, wordt het gebruik van een data handler sterk aanbevolen voor de meeste toepassingen. De data handler :

• Handelt gebeurtenissen uit de gebeurtenissenstroom
• Bewaart de gegevens in zijn opslaglaag
• Biedt een app de middelen om callbacks te krijgen voor gebeurtenissen
• Biedt en onderhoudt kamerobjecten voor kamer-specifieke operaties (berichten krijgen, toetreden, schoppen, uitnodigen, enz.)

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

maakt een data handler met de standaard in-memory storage implementatie.

Registreert een listener

Om op de hoogte te zijn van gebeurtenissen, moet de app een event listener implementeren.

session.getDataHandler().addListener(eventListener);

Deze luisteraar moet een subklasse van MXEventListener zijn en de methoden naar behoefte overschrijven:

onPresenceUpdate(event, user) Getriggerd wanneer de aanwezigheid van een gebruiker is bijgewerkt.

onLiveEvent(event, roomState) Getriggerd wanneer een live gebeurtenis is binnengekomen in de gebeurtenisstroom.

onBackEvent(event, roomState) Getriggerd wanneer een oude gebeurtenis (uit de geschiedenis), of een teruggeplaatste gebeurtenis, is teruggekeerd na een verzoek om meer geschiedenis.

onInitialSyncComplete() Getriggerd wanneer het initiële synchronisatieproces is voltooid. De initiële synchronisatie is de eerste oproep die de gebeurtenissenstroom doet om de status van alle bekende kamers, gebruikers, enzovoort te initialiseren.

Het kamerobject

Het kamerobject bevat methoden voor interactie met een kamer (opvragen van berichtgeschiedenis, lid worden, enzovoort).

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

Krijgt (of maakt) het kamerobject dat is gekoppeld aan de opgegeven kamer-ID.

Kamertoestand

Het object Kamertoestand geeft de toestand van de kamer op een bepaald moment weer: naam, onderwerp, zichtbaarheid (openbaar/privé), leden, enz. onLiveEvent en onBackEvent callbacks (zie Een luisteraar registreren) retourneren het evenement, maar ook de toestand van de kamer op het moment van het evenement om als context te dienen voor het opbouwen van de weergave (bijvoorbeeld de schermnaam van de gebruiker op het moment van zijn bericht). De toestand is de toestand voor het verwerken van de gebeurtenis, als de gebeurtenis de toestand van de kamer verandert.

Geschiedenis van de kamer

Wanneer een app een kamer binnengaat, wil hij meestal de laatste berichten tonen. Dit wordt gedaan door

room.requestHistory();

De gebeurtenissen worden dan geretourneerd via de onBackEvent(event, roomState) callback in omgekeerde volgorde (meest recente eerst).

Dit triggert niet dat de hele geschiedenis van de kamer wordt geretourneerd, maar slechts ongeveer 15 berichten. Opnieuw requestHistory() aanroepen zal dan de volgende (eerdere) 15 of zo ophalen, enzovoort. Om de geschiedenis op te vragen vanuit de huidige live-status (bijvoorbeeld bij het openen of heropenen van een kamer), moet

room.initHistory();

worden aangeroepen voordat de geschiedenis wordt opgevraagd.

De content manager

Matrix home servers bieden een content API voor het downloaden en uploaden van content (afbeeldingen, video’s, bestanden, etc.).De contentmanager biedt een omhulsel van die API.

session.getContentManager();

Haal de contentmanager op die bij de gegeven sessie hoort.

Content downloaden

Content die door een homeserver wordt gehost, wordt geïdentificeerd (in gebeurtenissen, avatar-URL’s, enzovoort) door een URI met een mxc-schema (mxc://matrix.org/xxxx bijvoorbeeld).Om de onderliggende HTTP URI voor het ophalen van de inhoud te verkrijgen, gebruikt u

contentManager.getDownloadableUrl(contentUrl);

waarbij contentUrl de mxc:// content URL is.

Voor afbeeldingen bestaat er een extra methode voor het retourneren van miniaturen in plaats van afbeeldingen op ware grootte:

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

waarmee u een specifieke breedte, hoogte en schaalmethode (tussen schaal en bijsnijden) kunt opvragen.

Uploaden van inhoud

Om inhoud van een bestand te uploaden, gebruikt u

contentManager.uploadContent(filePath, callback);

specifieer het bestandspad en een callback-methode die bij voltooiing een object teruggeeft dat de mxc-stijl URI bevat waar de geüploade inhoud nu kan worden gevonden.

Zie de voorbeeld-app en Javadoc voor meer details.