Matrix.org Android SDK

The [Matrix] SDK for Android wraps the Matrix REST API calls in asynchronous Java methods and provides basic structures for storing and handling data.

It is an Android Studio (gradle) project containing the SDK module. https://github.com/vector-im/riot-android is the sample app which uses this SDK.

Overview

The Matrix APIs are split into several categories (see [matrix api]). Basic usage is:

1. Log in or register to a home server -> get the user's credentials
2. Start a session with the credentials
3. Start listening to the event stream
4. Make matrix API calls

Logging in

To log in, use an instance of the login API client.

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

If successful, the callback will provide the user credentials to use from then on.

Starting the matrix session

The session represents one user's session with a particular home server. There can potentially be multiple sessions for handling multiple accounts.

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

sets up a session for interacting with the home server.

The session gives access to the different APIs through the REST clients:

session.getEventsApiClient() for the events API

session.getProfileApiClient() for the profile API

session.getPresenceApiClient() for the presence API

session.getRoomsApiClient() for the rooms API

For the complete list of methods, please refer to the [Javadoc].

Example Getting the list of members of a chat room would look something like this:

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

The same session object should be used for each request. This may require use of a singleton, see the Matrix singleton in the app module for an example.

The event stream

One important part of any Matrix-enabled app will be listening to the event stream, the live flow of events (messages, state changes, etc.). This is done by using:

session.startEventStream();

This starts the events thread and sets it to send events to a default listener. It may be useful to use this in conjunction with an Android Service to control whether the event stream is running in the background or not.

The data handler

The data handler provides a layer to help manage data from the events stream. While it is possible to write an app with no data handler and manually make API calls, using one is highly recommended for most uses. The data handler :

• Handles events from the events stream
• Stores the data in its storage layer
• Provides the means for an app to get callbacks for events
• Provides and maintains room objects for room-specific operations (getting messages, joining, kicking, inviting, etc.)

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

creates a data handler with the default in-memory storage implementation.

Registering a listener

To be informed of events, the app needs to implement an event listener.

session.getDataHandler().addListener(eventListener);

This listener should subclass MXEventListener and override the methods as needed:

onPresenceUpdate(event, user) Triggered when a user's presence has been updated.

onLiveEvent(event, roomState) Triggered when a live event has come down the event stream.

onBackEvent(event, roomState) Triggered when an old event (from history), or back event, has been returned after a request for more history.

onInitialSyncComplete() Triggered when the initial sync process has completed. The initial sync is the first call the event stream makes to initialize the state of all known rooms, users, etc.

The Room object

The Room object provides methods to interact with a room (getting message history, joining, etc).

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

gets (or creates) the room object associated with the given room ID.

Room state

The RoomState object represents the room's state at a certain point in time: its name, topic, visibility (public/private), members, etc. onLiveEvent and onBackEvent callbacks (see Registering a listener) return the event, but also the state of the room at the time of the event to serve as context for building the display (e.g. the user's display name at the time of their message). The state provided is the one before processing the event, if the event happens to change the state of the room.

Room history

When entering a room, an app usually wants to display the last messages. This is done by calling

room.requestHistory();

The events are then returned through the onBackEvent(event, roomState) callback in reverse order (most recent first).

This does not trigger all of the room's history to be returned but only about 15 messages. Calling requestHistory() again will then retrieve the next (earlier) 15 or so, and so on. To start requesting history from the current live state (e.g. when opening or reopening a room),

room.initHistory();

must be called prior to the history requests.

The content manager

Matrix home servers provide a content API for the downloading and uploading of content (images, videos, files, etc.). The content manager provides the wrapper around that API.

session.getContentManager();

retrieves the content manager associated with the given session.

Downloading content

Content hosted by a home server is identified (in events, avatar URLs, etc.) by a URI with a mxc scheme (mxc://matrix.org/xxxx for example). To obtain the underlying HTTP URI for retrieving the content, use

contentManager.getDownloadableUrl(contentUrl);

where contentUrl is the mxc:// content URL.

For images, an additional method exists for returning thumbnails instead of full-sized images:

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

which allows you to request a specific width, height, and scale method (between scale and crop).

Uploading content

To upload content from a file, use

contentManager.uploadContent(filePath, callback);

specifying the file path and a callback method which will return an object on completion containing the mxc-style URI where the uploaded content can now be found.

See the sample app and Javadoc for more details.