{"id":13549494,"url":"https://github.com/matrix-org/matrix-android-sdk","last_synced_at":"2025-04-02T22:32:02.288Z","repository":{"id":21318444,"uuid":"24635052","full_name":"matrix-org/matrix-android-sdk","owner":"matrix-org","description":"The Matrix SDK for Android - DEPRECATED","archived":true,"fork":false,"pushed_at":"2022-02-08T09:00:16.000Z","size":56099,"stargazers_count":371,"open_issues_count":31,"forks_count":132,"subscribers_count":63,"default_branch":"develop","last_synced_at":"2024-11-03T18:35:02.074Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matrix-org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-09-30T11:09:12.000Z","updated_at":"2024-10-19T23:49:27.000Z","dependencies_parsed_at":"2022-08-20T18:00:53.649Z","dependency_job_id":null,"html_url":"https://github.com/matrix-org/matrix-android-sdk","commit_stats":null,"previous_names":[],"tags_count":70,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-android-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-android-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-android-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-android-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matrix-org","download_url":"https://codeload.github.com/matrix-org/matrix-android-sdk/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246905398,"owners_count":20852815,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T12:01:22.386Z","updated_at":"2025-04-02T22:32:00.087Z","avatar_url":"https://github.com/matrix-org.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"[![Buildkite](https://badge.buildkite.com/c080f1de5e60c792fab17531dfda61ee0c3178ec616cfccb29.svg?branch=develop)](https://buildkite.com/matrix-dot-org/matrix-android-sdk)\n[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=matrix.android.sdk\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=matrix.android.sdk)\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=matrix.android.sdk\u0026metric=vulnerabilities)](https://sonarcloud.io/project/issues?id=matrix.android.sdk\u0026resolved=false\u0026types=VULNERABILITY)\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=matrix.android.sdk\u0026metric=bugs)](https://sonarcloud.io/project/issues?id=matrix.android.sdk\u0026resolved=false\u0026types=BUG) \n\nImportant Announcement\n======================\n\nThis SDK is deprecated and the core team does not work anymore on it.\n\nWe strongly recommends that new projects use [the new Android Matrix SDK](https://github.com/matrix-org/matrix-android-sdk2).\n\nWe can provide best effort support for existing projects that are still using this SDK though.\n\nmatrix-android-sdk\n==================\nThe [Matrix] SDK for Android wraps the Matrix REST API calls in asynchronous Java methods and provides basic structures for storing and handling data.\n\nIt is an Android Studio (gradle) project containing the SDK module.\nhttps://github.com/vector-im/riot-android is the sample app which uses this SDK.\n\nOverview\n--------\nThe Matrix APIs are split into several categories (see [matrix api]).\nBasic usage is:\n\n 1. Log in or register to a home server -\u003e get the user's credentials\n 2. Start a session with the credentials\n 3. Start listening to the event stream\n 3. Make matrix API calls\n\nBugs / Feature Requests\n-----------------------\nThink you've found a bug? Please check if an issue\ndoes not exist yet, then, if not, open an issue on this Github repo. If an issue already\nexists, feel free to upvote for it.\n\nContributing\n------------\nWant to fix a bug or add a new feature? Check if there is an corresponding opened issue.\nIf no one is actively working on the issue, then please fork\nthe ``develop`` branch when writing your fix, and open a pull request when you're\nready. Do not base your pull requests off ``master``.\n\nLogging in\n----------\nTo log in, use an instance of the login API client.\n\n```java\nHomeServerConnectionConfig hsConfig = new HomeServerConnectionConfig.Builder()\n    .withHomeServerUri(Uri.parse(\"https://matrix.org\"))\n    .build();\nnew LoginRestClient(hsConfig).loginWithUser(username, password, new SimpleApiCallback\u003cCredentials\u003e());\n```\n\nIf successful, the callback will provide the user credentials to use from then on.\n\nStarting the matrix session\n---------------------------\nThe session represents one user's session with a particular home server. There can potentially be multiple sessions for handling multiple accounts.\n\n```java\nMXSession session = new MXSession.Builder(hsConfig, new MXDataHandler(store, credentials), getApplicationContext())\n    .build();\n```\n\nsets up a session for interacting with the home server.\n\nThe session gives access to the different APIs through the REST clients:\n\n```session.getEventsApiClient()``` for the events API\n\n```session.getProfileApiClient()``` for the profile API\n\n```session.getPresenceApiClient()``` for the presence API\n\n```session.getRoomsApiClient()``` for the rooms API\n\nFor the complete list of methods, please refer to the [Javadoc].\n\n**Example**\nGetting the list of members of a chat room would look something like this:\n\n```java\nsession.getRoomsApiClient().getRoomMembers(\u003croomId\u003e, callback);\n```\n\nThe same session object should be used for each request. This may require use\nof a singleton, see the ```Matrix``` singleton in the ```app``` module for an\nexample.\n\nThe event stream\n----------------\nOne important part of any Matrix-enabled app will be listening to the event stream, the live flow of events (messages, state changes, etc.).\nThis is done by using:\n\n```java\nsession.startEventStream();\n```\n\nThis starts the events thread and sets it to send events to a default listener.\nIt may be useful to use this in conjunction with an Android ```Service``` to\ncontrol whether the event stream is running in the background or not.\n\nThe data handler\n----------------\nThe data handler provides a layer to help manage data from the events stream. While it is possible to write an app with no\ndata handler and manually make API calls, using one is highly recommended for most uses. The data handler :\n\n * Handles events from the events stream\n * Stores the data in its storage layer\n * Provides the means for an app to get callbacks for events\n * Provides and maintains room objects for room-specific operations (getting messages, joining, kicking, inviting, etc.)\n\n```java\nMXDataHandler dataHandler = new MXDataHandler(new MXMemoryStore());\n```\n\ncreates a data handler with the default in-memory storage implementation.\n\n### Registering a listener\nTo be informed of events, the app needs to implement an event listener.\n\n```java\nsession.getDataHandler().addListener(eventListener);\n```\n\nThis listener should subclass ```MXEventListener``` and override the methods as needed:\n\n```onPresenceUpdate(event, user) ```\nTriggered when a user's presence has been updated.\n\n```onLiveEvent(event, roomState) ```\nTriggered when a live event has come down the event stream.\n\n```onBackEvent(event, roomState) ```\nTriggered when an old event (from history), or back event, has been returned after a request for more history.\n\n```onInitialSyncComplete() ```\nTriggered when the initial sync process has completed. The initial sync is the first call the event stream makes\nto initialize the state of all known rooms, users, etc.\n\n### The Room object\nThe Room object provides methods to interact with a room (getting message history, joining, etc).\n\n```java\nRoom room = session.getDataHandler().getRoom(roomId);\n```\n\ngets (or creates) the room object associated with the given room ID.\n\n#### Room state\nThe RoomState object represents the room's state at a certain point in time: its name, topic, visibility (public/private), members, etc.\nonLiveEvent and onBackEvent callbacks (see Registering a listener) return the event, but also the state of the room at the time of the event to\nserve 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\nprocessing the event, if the event happens to change the state of the room.\n\n#### Room history\nWhen entering a room, an app usually wants to display the last messages. This is done by calling\n\n```java\nroom.requestHistory();\n```\n\nThe events are then returned through the ```onBackEvent(event, roomState)``` callback in reverse order (most recent first).\n\nThis does not trigger all of the room's history to be returned but only about 15 messages. Calling ```requestHistory()``` again will then\nretrieve 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),\n\n```java\nroom.initHistory();\n```\n\nmust be called prior to the history requests.\n\nThe content manager\n-------------------\nMatrix home servers provide a content API for the downloading and uploading of content (images, videos, files, etc.).\nThe content manager provides the wrapper around that API.\n\n```java\nsession.getContentManager();\n```\n\nretrieves the content manager associated with the given session.\n\n### Downloading content\nContent 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).\nTo obtain the underlying HTTP URI for retrieving the content, use\n\n```java\ncontentManager.getDownloadableUrl(contentUrl);\n```\n\nwhere contentUrl is the mxc:// content URL.\n\nFor images, an additional method exists for returning thumbnails instead of full-sized images:\n\n```java\ncontentManager.getDownloadableThumbnailUrl(contentUrl, width, height, method);\n```\n\nwhich allows you to request a specific width, height, and scale method (between scale and crop).\n\n### Uploading content\nTo upload content from a file, use\n\n```java\ncontentManager.uploadContent(filePath, callback);\n```\n\nspecifying the file path and a callback method which will return an object on completion containing the mxc-style URI where the uploaded\ncontent can now be found.\n\n**See the sample app and Javadoc for more details.**\n\nReferences\n----------\n- [Matrix home page](https://matrix.org)\n- [Matrix api documentation](https://matrix.org/docs/spec/client_server/latest.html)\n- [Matrix api](https://matrix.org/docs/api/client-server/)\n\nLicense\n-------\nApache 2.0\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmatrix-android-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrix-org%2Fmatrix-android-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmatrix-android-sdk/lists"}