matrix-org / matrix-android-sdk

Ce SDK est déprécié et l’équipe centrale ne travaille plus dessus.

Nous recommandons fortement que les nouveaux projets utilisent le nouveau SDK Android Matrix.

Nous pouvons fournir un support best effort pour les projets existants qui utilisent encore ce SDK cependant.

matrix-android-sdk

Le SDK pour Android enveloppe les appels de l’API REST Matrix dans des méthodes Java asynchrones et fournit des structures de base pour le stockage et la manipulation des données.

Il s’agit d’un projet Android Studio (gradle) contenant le module SDK.https://github.com/vector-im/riot-android est l’application exemple qui utilise ce SDK.

Aperçu

Les API Matrix sont divisées en plusieurs catégories (voir ).L’utilisation de base est la suivante :

1. Connexion ou enregistrement à un serveur domestique -> obtenir les informations d’identification de l’utilisateur
2. Démarrer une session avec les informations d’identification
3. Démarrer l’écoute du flux d’événements
4. Faire des appels API matriciels

Bugs / Feature Requests

Pensez avoir trouvé un bug ? Veuillez vérifier si une issue n’existe pas encore, puis, si non, ouvrez une issue sur ce repo Github. Si une question existe déjà, n’hésitez pas à l’upvoter.

Contribuer

Vous voulez corriger un bug ou ajouter une nouvelle fonctionnalité ? Vérifiez s’il y a un problème ouvert correspondant.Si personne ne travaille activement sur le problème, alors veuillez fork la branche develop lors de l’écriture de votre correctif, et ouvrez une pull request lorsque vous êtes prêt. Ne basez pas vos demandes de pull sur master.

Connexion

Pour se connecter, utilisez une instance du client API de connexion.

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

En cas de succès, le callback fournira les informations d’identification de l’utilisateur à utiliser à partir de là.

Démarrage de la session de la matrice

La session représente la session d’un utilisateur avec un serveur domestique particulier. Il peut potentiellement y avoir plusieurs sessions pour gérer plusieurs comptes.

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

mise en place d’une session pour interagir avec le serveur domestique.

La session donne accès aux différentes API via les clients REST :

session.getEventsApiClient() pour l’API d’événements

session.getProfileApiClient() pour l’API de profil

session.getPresenceApiClient() pour l’API de présence

session.getRoomsApiClient() pour l’API de salles

Pour la liste complète des méthodes, veuillez vous référer à la .

ExempleL’obtention de la liste des membres d’une salle de discussion ressemblerait à ceci :

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

Le même objet de session doit être utilisé pour chaque requête. Cela peut nécessiter l’utilisation d’un singleton, voir le singleton Matrix dans le module app pour unexemple.

Le flux d’événements

Une partie importante de toute application compatible avec Matrix sera l’écoute du flux d’événements, le flux en direct des événements (messages, changements d’état, etc.).Ceci est fait en utilisant :

session.startEventStream();

Ceci démarre le fil d’événements et le configure pour envoyer des événements à un auditeur par défaut.Il peut être utile d’utiliser ceci en conjonction avec un Android Service pour contrôler si le flux d’événements est exécuté en arrière-plan ou non.

Le gestionnaire de données

Le gestionnaire de données fournit une couche pour aider à gérer les données du flux d’événements. Bien qu’il soit possible d’écrire une application avec nodata handler et de faire manuellement des appels API, en utiliser un est fortement recommandé pour la plupart des utilisations. Le gestionnaire de données :

• Gère les événements provenant du flux d’événements
• Stocke les données dans sa couche de stockage
• Fournit le moyen pour une app d’obtenir des callbacks pour les événements
• Fournit et maintient les objets de salle pour les opérations spécifiques à la salle (obtenir des messages, rejoindre, donner des coups de pied, inviter, etc.)

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

crée un gestionnaire de données avec l’implémentation de stockage en mémoire par défaut.

Enregistrement d’un écouteur

Pour être informée des événements, l’app doit implémenter un écouteur d’événements.

session.getDataHandler().addListener(eventListener);

Cet écouteur doit sous-classer MXEventListener et surcharger les méthodes au besoin :

onPresenceUpdate(event, user) Déclenché lorsque la présence d’un utilisateur a été mise à jour.

onLiveEvent(event, roomState) Déclenché lorsqu’un événement en direct est descendu dans le flux d’événements.

onBackEvent(event, roomState) Déclenché lorsqu’un ancien événement (de l’historique), ou un événement de retour, a été retourné après une demande pour plus d’historique.

onInitialSyncComplete() Déclenché lorsque le processus de synchronisation initiale est terminé. La synchronisation initiale est le premier appel que le flux d’événements fait pour initialiser l’état de toutes les salles connues, des utilisateurs, etc.

L’objet Salle

L’objet Salle fournit des méthodes pour interagir avec une salle (obtenir l’historique des messages, rejoindre, etc).

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

obtient (ou crée) l’objet salle associé à l’ID de salle donné.

État de la salle

L’objet RoomState représente l’état de la salle à un moment donné : son nom, son sujet, sa visibilité (publique/privée), ses membres, etc.Les callbacks onLiveEvent et onBackEvent (voir Enregistrer un écouteur) renvoient l’événement, mais aussi l’état de la salle au moment de l’événement pour servir de contexte à la construction de l’affichage (par exemple, le nom d’affichage de l’utilisateur au moment de son message). L’état fourni est celui avant le traitement de l’événement, si l’événement se trouve changer l’état de la pièce.

Historique de la pièce

Lorsqu’on entre dans une pièce, une app veut généralement afficher les derniers messages. Cela se fait en appelant

room.requestHistory();

Les événements sont ensuite renvoyés par le callback onBackEvent(event, roomState) dans l’ordre inverse (le plus récent en premier).

Cela ne déclenche pas le renvoi de tout l’historique de la pièce mais seulement une quinzaine de messages. En appelant requestHistory() à nouveau, on récupère alors les 15 suivants (plus anciens), et ainsi de suite. Pour commencer à demander l’historique à partir de l’état actuel en direct (par exemple, lors de l’ouverture ou de la réouverture d’une pièce),

room.initHistory();

doit être appelé avant les demandes d’historique.

Le gestionnaire de contenu

Les serveurs domestiques Matrix fournissent une API de contenu pour le téléchargement et le chargement de contenu (images, vidéos, fichiers, etc.).Le gestionnaire de contenu fournit l’enveloppe autour de cette API.

session.getContentManager();

récupère le gestionnaire de contenu associé à la session donnée.

Téléchargement de contenu

Le contenu hébergé par un serveur domestique est identifié (dans les événements, les URL d’avatar, etc.) par un URI avec un schéma mxc (mxc://matrix.org/xxxx par exemple).Pour obtenir l’URI HTTP sous-jacent permettant de récupérer le contenu, utilisez

contentManager.getDownloadableUrl(contentUrl);

où contentUrl est l’URL de contenu mxc://.

Pour les images, une méthode supplémentaire existe pour renvoyer des vignettes au lieu d’images en taille réelle:

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

qui permet de demander une largeur, une hauteur et une méthode d’échelle (entre échelle et crop) spécifiques.

Téléchargement de contenu

Pour télécharger du contenu à partir d’un fichier, utilisez

contentManager.uploadContent(filePath, callback);

spécifiant le chemin du fichier et une méthode de rappel qui renverra un objet à la fin contenant l’URI de style mxc où le contenu téléchargé peut maintenant être trouvé.

Voir l’exemple d’application et la Javadoc pour plus de détails.