matrix-org / matrix-android-sdk
Este SDK está obsoleto y el equipo principal ya no trabaja en él.
Recomendamos encarecidamente que los nuevos proyectos utilicen el nuevo SDK de Matrix para Android.
Podemos proporcionar el mejor soporte posible para los proyectos existentes que todavía están utilizando este SDK.
matrix-android-sdk
El SDK para Android envuelve las llamadas a la API REST de Matrix en métodos Java asíncronos y proporciona estructuras básicas para almacenar y manejar datos.
Es un proyecto de Android Studio (gradle) que contiene el módulo SDK.https://github.com/vector-im/riot-android es la aplicación de ejemplo que utiliza este SDK.
Descripción general
Las APIs de Matrix se dividen en varias categorías (ver ).El uso básico es:
- Iniciar sesión o registrarse en un servidor de origen -> obtener las credenciales del usuario
- Iniciar una sesión con las credenciales
- Empezar a escuchar el flujo de eventos
- Hacer llamadas a la API de la matriz
Bugs / Feature Requests
¿Crees que has encontrado un bug? Por favor, comprueba si aún no existe una incidencia, y si no es así, abre una incidencia en este repositorio de Github. Si ya existe una incidencia, no dudes en votar por ella.
Contribuir
¿Quieres arreglar un error o añadir una nueva característica? Si no hay nadie trabajando activamente en el problema, por favor, busca la rama develop cuando escribas tu solución, y abre un pull request cuando estés listo. No base sus solicitudes de pull en master.
Iniciar sesión
Para iniciar sesión, utilice una instancia del cliente de la API de inicio de sesión.
HomeServerConnectionConfig hsConfig = new HomeServerConnectionConfig.Builder() .withHomeServerUri(Uri.parse("https://matrix.org")) .build();new LoginRestClient(hsConfig).loginWithUser(username, password, new SimpleApiCallback<Credentials>());
Si tiene éxito, la devolución de llamada proporcionará las credenciales de usuario para utilizar a partir de entonces.
Iniciar la sesión de la matriz
La sesión representa la sesión de un usuario con un servidor de inicio particular. Puede haber potencialmente múltiples sesiones para manejar múltiples cuentas.
MXSession session = new MXSession.Builder(hsConfig, new MXDataHandler(store, credentials), getApplicationContext()) .build();
Establece una sesión para interactuar con el servidor de origen.
La sesión da acceso a las diferentes APIs a través de los clientes REST:
session.getEventsApiClient() para la API de eventos
session.getProfileApiClient() para la API de perfiles
session.getPresenceApiClient() para la API de presencia
session.getRoomsApiClient() para la API de habitaciones
Para la lista completa de métodos, por favor, consulte el .
EjemploObtener la lista de miembros de una sala de chat sería algo así:
session.getRoomsApiClient().getRoomMembers(<roomId>, callback);
Se debe utilizar el mismo objeto de sesión para cada solicitud. Esto puede requerir el uso de un singleton, ver el singleton Matrix en el módulo app para un ejemplo.
El flujo de eventos
Una parte importante de cualquier aplicación habilitada para Matrix será escuchar el flujo de eventos, el flujo en vivo de eventos (mensajes, cambios de estado, etc.).Esto se hace mediante el uso de:
session.startEventStream();
Esto inicia el hilo de eventos y lo establece para enviar eventos a un oyente por defecto.Puede ser útil utilizar esto en conjunción con un Android Service para controlar si el flujo de eventos se ejecuta en el fondo o no.
El manejador de datos
El manejador de datos proporciona una capa para ayudar a gestionar los datos del flujo de eventos. Aunque es posible escribir una aplicación con un manejador de datos y hacer manualmente las llamadas a la API, el uso de uno es muy recomendable para la mayoría de los usos. El manejador de datos :
- Maneja los eventos del flujo de eventos
- Almacena los datos en su capa de almacenamiento
- Proporciona los medios para que una app obtenga callbacks para los eventos
- Proporciona y mantiene objetos de sala para operaciones específicas de la sala (obtener mensajes, unirse, patear, invitar, etc.)
MXDataHandler dataHandler = new MXDataHandler(new MXMemoryStore());
crea un manejador de datos con la implementación de almacenamiento en memoria por defecto.
Registrar un listener
Para estar informado de los eventos, la app necesita implementar un listener de eventos.
session.getDataHandler().addListener(eventListener);
Este listener debe subclasificar MXEventListener y anular los métodos según sea necesario:
onPresenceUpdate(event, user) Se activa cuando la presencia de un usuario se ha actualizado.
onLiveEvent(event, roomState) Se activa cuando un evento en vivo ha llegado al flujo de eventos.
onBackEvent(event, roomState) Se dispara cuando un evento antiguo (del historial), o un evento atrasado, ha sido devuelto después de una solicitud de más historial.
onInitialSyncComplete() Se dispara cuando el proceso de sincronización inicial se ha completado. La sincronización inicial es la primera llamada que hace el flujo de eventos para inicializar el estado de todas las salas conocidas, usuarios, etc.
El objeto Sala
El objeto Sala proporciona métodos para interactuar con una sala (obtener el historial de mensajes, unirse, etc).
Room room = session.getDataHandler().getRoom(roomId);
Obtiene (o crea) el objeto sala asociado con el ID de sala dado.
Estado de la sala
El objeto RoomState representa el estado de la sala en un momento determinado: su nombre, tema, visibilidad (pública/privada), miembros, etc.Las devoluciones de llamada onLiveEvent y onBackEvent (ver Registro de un oyente) devuelven el evento, pero también el estado de la sala en el momento del evento para que sirva de contexto para la construcción de la pantalla (por ejemplo, el nombre de la pantalla del usuario en el momento de su mensaje). El estado proporcionado es el que había antes de procesar el evento, si el evento cambia el estado de la sala.
Historial de la sala
Cuando se entra en una sala, una aplicación suele querer mostrar los últimos mensajes. Esto se hace llamando a
room.requestHistory();
Los eventos se devuelven a través de la llamada de retorno onBackEvent(event, roomState) en orden inverso (el más reciente primero).
Esto no provoca que se devuelva todo el historial de la sala sino sólo unos 15 mensajes. Al llamar de nuevo a requestHistory() se recuperarán los siguientes 15 mensajes (anteriores), y así sucesivamente. Para empezar a solicitar el historial desde el estado actual (por ejemplo, al abrir o reabrir una sala),
room.initHistory();
debe llamarse antes de las solicitudes de historial.
El gestor de contenidos
Los servidores domésticos de Matrix proporcionan una API de contenidos para la descarga y subida de contenidos (imágenes, vídeos, archivos, etc.).El gestor de contenidos proporciona la envoltura alrededor de esa API.
session.getContentManager();
recupera el gestor de contenidos asociado a la sesión dada.
Descarga de contenidos
Los contenidos alojados en un servidor doméstico se identifican (en eventos, URLs de avatares, etc.) por una URI con un esquema mxc (mxc://matrix.org/xxxx por ejemplo).Para obtener la URI HTTP subyacente para recuperar el contenido, utilice
contentManager.getDownloadableUrl(contentUrl);
donde contentUrl es la URL mxc:// del contenido.
Para las imágenes, existe un método adicional para devolver miniaturas en lugar de imágenes de tamaño completo:
contentManager.getDownloadableThumbnailUrl(contentUrl, width, height, method);
que permite solicitar un ancho, un alto y un método de escala específicos (entre escala y recorte).
Subir contenido
Para subir contenido desde un archivo, utilice
contentManager.uploadContent(filePath, callback);
especificando la ruta del archivo y un método de devolución de llamada que devolverá un objeto al finalizar que contiene el URI de estilo mxc donde ahora se puede encontrar el contenido subido.
Vea la aplicación de ejemplo y Javadoc para más detalles.