matrix-org / matrix-android-sdk
Este SDK é depreciado e a equipe central não trabalha mais nele.
Recomendamos fortemente que novos projetos usem o novo SDK Matrix para Android.
Podemos fornecer suporte de melhor esforço para projetos existentes que ainda estão usando este SDK.
matrix-android-sdk
O SDK para Android envolve as chamadas da API Matrix REST em métodos Java assíncronos e fornece estruturas básicas para armazenamento e manuseio de dados.
É um projeto Android Studio (gradle) contendo o módulo SDK.https://github.com/vector-im/riot-androidé a aplicação de exemplo que usa este SDK.
Visão geral
As APIs Matrix são divididas em várias categorias (veja ).O uso básico é:
- Entrar ou registrar em um servidor home -> Obter as credenciais do usuário
- Iniciar uma sessão com as credenciais
- Iniciar ouvindo o fluxo de eventos
- Fazer chamadas de APIs Matrix
Bugs / Solicitações de recursos
Acha que encontrou um bug? Por favor, verifique se ainda não existe um issueoes, então, se não, abra um issue nesta repo do Github. Se um problema já existir, sinta-se à vontade para evitá-lo.
Contribuir
Deseja corrigir um bug ou adicionar um novo recurso? Se ninguém estiver trabalhando ativamente no problema, então forkthe develop branch quando escrever sua correção, e abra um pedido de puxar quando você estiver pronto. Não baseie suas requisições pull em master.
Log in
Para log in, use uma instância do cliente da API de login.
HomeServerConnectionConfig hsConfig = new HomeServerConnectionConfig.Builder() .withHomeServerUri(Uri.parse("https://matrix.org")) .build();new LoginRestClient(hsConfig).loginWithUser(username, password, new SimpleApiCallback<Credentials>());
Se bem sucedida, a callback irá fornecer as credenciais do usuário para usar a partir daí.
Iniciando a sessão da matriz
A sessão representa a sessão de um usuário com um servidor home em particular. Pode haver potencialmente várias sessões para lidar com várias contas.
MXSession session = new MXSession.Builder(hsConfig, new MXDataHandler(store, credentials), getApplicationContext()) .build();
configura uma sessão para interagir com o servidor home.
A sessão dá acesso às diferentes APIs através dos clientes REST:
session.getEventsApiClient() para os eventos API
session.getProfileApiClient() para o perfil API
session.getPresenceApiClient() para a presença API
session.getRoomsApiClient() para as salas API
Para a lista completa de métodos, por favor consulte a página .
ExemploEncontrar a lista de membros de uma sala de chat seria algo parecido com isto:
session.getRoomsApiClient().getRoomMembers(<roomId>, callback);
O mesmo objecto de sessão deve ser usado para cada pedido. Isto pode requerer o uso de um singleton, veja o singleton Matrix no módulo app para anexample.
O fluxo de eventos
Uma parte importante de qualquer aplicativo habilitado para Matrix será ouvir o fluxo de eventos, o fluxo de eventos ao vivo (mensagens, mudanças de estado, etc.).Isto é feito usando:
session.startEventStream();
Isto inicia o thread de eventos e o define para enviar eventos para um ouvinte padrão. Pode ser útil usar isto em conjunto com um Android Service tocontrol se o stream de eventos está rodando em segundo plano ou não.
O manipulador de dados
O manipulador de dados fornece uma camada para ajudar a gerenciar os dados do stream de eventos. Enquanto é possível escrever um aplicativo com o manipulador de nodata e fazer chamadas API manualmente, o uso de um é altamente recomendado para a maioria dos usos. O manipulador de dados :
- Agenda eventos do fluxo de eventos
- Armazena os dados em sua camada de armazenamento
- Provê os meios para uma aplicação obter callbacks para eventos
- Provê e mantém objetos de sala para operações específicas da sala (receber mensagens, juntar, chutar, convidar, etc.).)
MXDataHandler dataHandler = new MXDataHandler(new MXMemoryStore());
cria um manipulador de dados com a implementação padrão de armazenamento em memória.
Registar um ouvinte
Para ser informado dos eventos, o aplicativo precisa implementar um ouvinte de eventos.
session.getDataHandler().addListener(eventListener);
Este ouvinte deve subclassificar MXEventListener e substituir os métodos conforme necessário:
onPresenceUpdate(event, user) Acionado quando a presença de um usuário foi atualizada.
onLiveEvent(event, roomState) Acionado quando um evento ao vivo desceu no fluxo de eventos.
onBackEvent(event, roomState) Acionado quando um evento antigo (do histórico), ou evento de volta, foi retornado após um pedido de mais histórico.
onInitialSyncComplete() Acionado quando o processo de sincronização inicial foi concluído. A sincronização inicial é a primeira chamada que o fluxo de eventos faz para inicializar o estado de todas as salas conhecidas, usuários, etc.
O objeto Sala
O objeto Sala fornece métodos para interagir com uma sala (obter histórico de mensagens, juntar, etc).
Room room = session.getDataHandler().getRoom(roomId);
esquece (ou cria) o objeto Sala associado com o ID da sala em questão.
Estado da sala
O objeto RoomState representa o estado da sala em um determinado momento: seu nome, tópico, visibilidade (público/privado), membros, etc.onLiveEvent e onBackEvent callbacks (veja Registrando um ouvinte) retornam o evento, mas também o estado da sala no momento do evento toserve como contexto para construir a exibição (por exemplo, o nome da exibição do usuário no momento de sua mensagem). O estado fornecido é o estado anterior ao processamento do evento, se o evento mudar o estado da sala.
Histórico da sala
Ao entrar em uma sala, um aplicativo normalmente quer exibir as últimas mensagens. Isto é feito ligando para
room.requestHistory();
Os eventos são então retornados através do arquivo onBackEvent(event, roomState) callback em ordem reversa (o mais recente primeiro).
Isto não aciona todo o histórico da sala para ser retornado, mas apenas cerca de 15 mensagens. A chamada requestHistory() novamente irá então retornar a próxima (anterior) 15 ou mais, e assim por diante. Para começar a solicitar o histórico do estado atual ao vivo (por exemplo, ao abrir ou reabrir uma sala),
room.initHistory();
deve ser chamado antes dos pedidos de histórico.
O gerenciador de conteúdo
Servidores domésticos Matrix fornecem uma API de conteúdo para o download e upload de conteúdo (imagens, vídeos, arquivos, etc.).O gerenciador de conteúdo fornece o wrapper em torno dessa API.
session.getContentManager();
recupera o gerenciador de conteúdo associado à sessão dada.
Baixando conteúdo
Conteúdo hospedado por um servidor home é identificado (em eventos, URLs de avatares, etc.) por um URI com um esquema mxc (mxc://matrix.org/xxxx por exemplo).Para obter o URI HTTP subjacente para recuperar o conteúdo, use
contentManager.getDownloadableUrl(contentUrl);
onde contentUrl é a URL mxc:// content URL.
Para imagens, existe um método adicional para retornar miniaturas em vez de imagens em tamanho real:
contentManager.getDownloadableThumbnailUrl(contentUrl, width, height, method);
que permite solicitar um método específico de largura, altura e escala (entre escala e corte).
>
Carregar conteúdo
Para carregar conteúdo de um arquivo, use
contentManager.uploadContent(filePath, callback);
especificando o caminho do arquivo e um método de retorno que retornará um objeto após a conclusão contendo o URI estilo mxc onde o conteúdo carregado pode agora ser encontrado.
Veja o aplicativo de amostra e Javadoc para mais detalhes.