matrix-org / matrix-android-sdk
Ten SDK jest przestarzały i zespół core już nad nim nie pracuje.
Silnie zalecamy, aby nowe projekty używały nowego Android Matrix SDK.
Możemy zapewnić najlepsze wsparcie dla istniejących projektów, które nadal używają tego SDK.
matrix-android-sdk
SDK dla Androida opakowuje wywołania Matrix REST API w asynchroniczne metody Java i zapewnia podstawowe struktury do przechowywania i obsługi danych.
Jest to projekt Android Studio (gradle) zawierający moduł SDK.https://github.com/vector-im/riot-androidjest to przykładowa aplikacja, która używa tego SDK.
Przegląd
Interfejsy API Matrixa są podzielone na kilka kategorii (patrz ).Podstawowe zastosowanie to:
- Zaloguj się lub zarejestruj na serwerze macierzystym ->poznaj poświadczenia użytkownika
- Rozpocznij sesję z poświadczeniami
- Rozpocznij nasłuchiwanie strumienia zdarzeń
- Wykonuj połączenia API macierzy
Błędy / Feature Requests
Myślisz, że znalazłeś błąd? Sprawdź, czy taki błąd jeszcze nie istnieje, a jeśli nie, otwórz zgłoszenie na tym repo na Githubie. Jeśli sprawa już istnieje, nie krępuj się zagłosować za nią.
Współtworzenie
Chcesz naprawić błąd lub dodać nową funkcję? Jeśli nikt nie pracuje aktywnie nad tym problemem, to proszę forkthe develop branch podczas pisania swojej poprawki, i otwórz pull request kiedy będziesz gotowy. Nie bazuj swoich pull requestów na master.
Logowanie
Aby się zalogować, użyj instancji klienta API logowania.
HomeServerConnectionConfig hsConfig = new HomeServerConnectionConfig.Builder() .withHomeServerUri(Uri.parse("https://matrix.org")) .build();new LoginRestClient(hsConfig).loginWithUser(username, password, new SimpleApiCallback<Credentials>());
Jeśli się powiedzie, wywołanie zwrotne dostarczy poświadczenia użytkownika do użycia od tego momentu.
Uruchamianie sesji macierzy
Sesja reprezentuje sesję jednego użytkownika z konkretnym serwerem macierzystym. Potencjalnie może istnieć wiele sesji do obsługi wielu kont.
MXSession session = new MXSession.Builder(hsConfig, new MXDataHandler(store, credentials), getApplicationContext()) .build();
Utwarza sesję do interakcji z serwerem macierzystym.
Sesja daje dostęp do różnych interfejsów API za pośrednictwem klientów REST:
session.getEventsApiClient() dla interfejsu API zdarzeń
session.getProfileApiClient() dla interfejsu API profilu
session.getPresenceApiClient() dla interfejsu API obecności
session.getRoomsApiClient() dla interfejsu API pomieszczeń
Pełną listę metod można znaleźć w .
PrzykładPobranie listy członków pokoju rozmów wyglądałoby mniej więcej tak:
session.getRoomsApiClient().getRoomMembers(<roomId>, callback);
Ten sam obiekt sesji powinien być używany dla każdego żądania. Może to wymagać użycia singletonu, zobacz Matrix singleton w module app dla przykładu.
Strumień zdarzeń
Jedną z ważnych części każdej aplikacji obsługującej Matrix będzie nasłuchiwanie strumienia zdarzeń, przepływu zdarzeń na żywo (wiadomości, zmiany stanu, itp.).Można to zrobić za pomocą:
session.startEventStream();
To uruchamia wątek zdarzeń i ustawia go na wysyłanie zdarzeń do domyślnego słuchacza.Może być użyteczne użycie tego w połączeniu z Androidem Service do kontrolowania, czy strumień zdarzeń działa w tle, czy nie.
Ręcznik danych
Ręcznik danych zapewnia warstwę, która pomaga zarządzać danymi ze strumienia zdarzeń. Chociaż możliwe jest napisanie aplikacji z nodata handler i ręczne wykonywanie wywołań API, używanie jednego z nich jest wysoce zalecane dla większości zastosowań. Data handler :
- Obsługuje zdarzenia ze strumienia zdarzeń
- Otrzymuje dane w swojej warstwie przechowywania
- Dostarcza środki dla aplikacji, aby uzyskać wywołania zwrotne dla zdarzeń
- Dostarcza i utrzymuje obiekty pokoju dla operacji specyficznych dla pokoju (otrzymywanie wiadomości, dołączanie, kopanie, zapraszanie, itp.)
MXDataHandler dataHandler = new MXDataHandler(new MXMemoryStore());
tworzy handler danych z domyślną implementacją przechowywania w pamięci.
Rejestrowanie słuchacza
Aby być informowanym o zdarzeniach, aplikacja musi zaimplementować słuchacza zdarzeń.
session.getDataHandler().addListener(eventListener);
Ten listener powinien podklasować MXEventListener i nadpisać metody według potrzeb:
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. Synchronizacja początkowa jest pierwszym wywołaniem, które strumień zdarzeń wykonuje w celu zainicjowania stanu wszystkich znanych pokoi, użytkowników itp.
Obiekt Room
Obiekt Room udostępnia metody interakcji z pokojem (uzyskiwanie historii wiadomości, dołączanie itp.).
Room room = session.getDataHandler().getRoom(roomId);
Uzyskuje (lub tworzy) obiekt pokoju powiązany z podanym identyfikatorem pokoju.
Stan pokoju
Obiekt RoomState reprezentuje stan pokoju w określonym momencie: jego nazwę, temat, widoczność (publiczny/prywatny), członków, itp.wywołania zwrotne onLiveEvent i onBackEvent (zobacz Rejestrowanie słuchacza) zwracają zdarzenie, ale także stan pokoju w czasie zdarzenia, aby posłużyć jako kontekst do budowania wyświetlacza (np. nazwa użytkownika w czasie jego wiadomości). Podany stan to ten przed przetworzeniem zdarzenia, jeśli zdarzenie zmienia stan pokoju.
Historia pokoju
Wchodząc do pokoju, aplikacja zazwyczaj chce wyświetlić ostatnie wiadomości. Odbywa się to przez wywołanie
room.requestHistory();
Zdarzenia są następnie zwracane przez wywołanie zwrotne onBackEvent(event, roomState) w odwrotnej kolejności (najpierw najnowsze).
Nie wywołuje to zwrócenia całej historii pokoju, ale tylko około 15 wiadomości. Ponowne wywołanie requestHistory() spowoduje pobranie następnych (wcześniejszych) 15 lub więcej, i tak dalej. Aby rozpocząć żądanie historii z bieżącego stanu na żywo (np. podczas otwierania lub ponownego otwierania pokoju),
room.initHistory();
musi być wywołane przed żądaniami historii.
Menedżer zawartości
Serwery macierzyste Matrix zapewniają API zawartości do pobierania i wysyłania zawartości (obrazów, wideo, plików itp.).Menedżer zawartości zapewnia opakowanie wokół tego API.
session.getContentManager();
wyszukuje menedżera zawartości powiązanego z daną sesją.
Pobieranie zawartości
Zawartość hostowana przez serwer macierzysty jest identyfikowana (w zdarzeniach, adresach URL awatarów itp.) przez URI ze schematem mxc (na przykład mxc://matrix.org/xxxx).Aby uzyskać bazowy HTTP URI do pobierania zawartości, użyj
contentManager.getDownloadableUrl(contentUrl);
gdzie contentUrl jest adresem URL mxc:// zawartości.
Dla obrazów istnieje dodatkowa metoda zwracania miniatur zamiast pełnowymiarowych obrazów:
contentManager.getDownloadableThumbnailUrl(contentUrl, width, height, method);
która pozwala zażądać określonej szerokości, wysokości i metody skali (między skalą a kadrowaniem).
Wgrywanie zawartości
Aby wgrać zawartość z pliku, użyj
contentManager.uploadContent(filePath, callback);
specyfikując ścieżkę pliku i metodę wywołania zwrotnego, która zwróci obiekt po zakończeniu, zawierający URI w stylu mxc, gdzie wgrana zawartość może być teraz znaleziona.
Zobacz przykładową aplikację i Javadoc po więcej szczegółów.