matrix-org / matrix-android-sdk
This SDK is deprecated and the core team does not work anymore on it.
We strongly recommended to use the new projects use the new Android Matrix SDK.This SDKは非推奨。
matrix-android-sdk
SD for Android は、Matrix REST API 呼び出しを非同期 Java メソッドでラップし、データを保存および処理する基本構造を提供します。
これは SDK モジュールを含む Android Studio (gradle) プロジェクトです。https://github.com/vector-im/riot-androidはこの SDK を使用するサンプル アプリです。
概要
MatrixのAPIはいくつかのカテゴリに分かれています (参照)。基本的な使用方法は以下のとおりです。
- ホームサーバーにログインまたは登録 -> ユーザーの認証情報を取得
- 認証情報を使用してセッションを開始
- イベントストリームのリスニングを開始
- Matrix API 呼び出し
Bugs / Feature Requests
何かバグがあったのでしょうか。 まだバグが存在しない場合は、この Github リポジトリにバグを登録してください。
Contributing
バグを修正したり、新しい機能を追加したいですか? もし誰もその問題に積極的に取り組んでいないのであれば、修正を書くときに develop ブランチをフォークし、準備ができたらプルリクエストを発行してください。
ログイン
ログインするには、ログイン API クライアントのインスタンスを使用します。
HomeServerConnectionConfig hsConfig = new HomeServerConnectionConfig.Builder() .withHomeServerUri(Uri.parse("https://matrix.org")) .build();new LoginRestClient(hsConfig).loginWithUser(username, password, new SimpleApiCallback<Credentials>());
成功すると、コールバックはそれ以降に使用するユーザー資格情報を提供します。 複数のアカウントを扱うために複数のセッションが存在する可能性があります。
MXSession session = new MXSession.Builder(hsConfig, new MXDataHandler(store, credentials), getApplicationContext()) .build();
ホームサーバーと対話するためのセッションを設定します。
セッションは、REST クライアントを通じてさまざまな API にアクセスできます。
session.getEventsApiClient() はイベント API、
session.getProfileApiClient() はプロファイル API、
session.getPresenceApiClient() はプレゼンス API、
session.getRoomsApiClient() はルーム API、
メソッドの全リストは、.NET アプリケーションを参照 してください。
例チャット ルームのメンバー リストの取得は次のようになります:
session.getRoomsApiClient().getRoomMembers(<roomId>, callback);
リクエストごとに同じセッション オブジェクトを使用する必要があります。 例として、app モジュールの Matrix シングルトンを参照してください。
イベント ストリーム
Matrix 対応アプリの重要な部分の 1 つは、イベントのライブ フロー (メッセージ、状態の変化など) であるイベント ストリームを聞くことでしょう。これは、
session.startEventStream();
を使用して行われます。これは、イベント スレッドを開始し、デフォルトのリスナーにイベントを送信するように設定します。 データ ハンドラを使ってアプリケーションを記述し、手動で API 呼び出しを行うことは可能ですが、ほとんどの用途ではデータ ハンドラの使用を強く推奨します。 データ ハンドラ:
- イベント ストリームからのイベントを処理する
- データをストレージ層に格納する
- アプリケーションにイベントのコールバック取得手段を提供する
- ルーム固有の操作 (メッセージ取得、参加、キック、招待、その他) のためにルーム オブジェクトを提供し維持する。)
MXDataHandler dataHandler = new MXDataHandler(new MXMemoryStore());
デフォルトのメモリ内ストレージ実装でデータ ハンドラを作成します。
リスナーを登録する
イベントの通知を受けるために、アプリはイベント リスナーを実装する必要があります。
session.getDataHandler().addListener(eventListener);
このリスナーは MXEventListener をサブクラス化し、必要に応じてメソッドをオーバーライドする必要があります：
onPresenceUpdate(event, user) ユーザーのプレゼンスが更新されるとトリガされます。
onBackEvent(event, roomState) 古いイベント（履歴から）、またはバックイベントが、より多くの履歴の要求後に返されたときにトリガされます。
onInitialSyncComplete() 最初の同期プロセスが完了したときにトリガされます。
Room オブジェクト
Room オブジェクトは、ルームと対話するためのメソッド (メッセージ履歴の取得、参加など) を提供します。
Room room = session.getDataHandler().getRoom(roomId);
与えられたルーム ID と関連付けられたルーム オブジェクトを取得 (または作成) します。
Room state
RoomState オブジェクトは、ある時点でのルームの状態を表します。その名前、トピック、可視性 (公開/非公開)、メンバーなど。onLiveEvent と onBackEvent コールバック (リスナーの登録を参照) はイベントを返しますが、表示を構築するコンテキストとして提供するイベントの時点の部屋の状態 (たとえば、ユーザーのメッセージがある時点でのユーザー表示名など) も返されます。
Room history
部屋に入るとき、アプリは通常、最後のメッセージを表示したいと思います。 これは、
room.requestHistory();
を呼び出すことにより行われます。
イベントは、onBackEvent(event, roomState) コールバックを通して逆順 (最新のものが最初) で返されます。 requestHistory() を再度呼び出すと、次の (以前の) 15件ほどが返され、これが繰り返されます。 現在のライブ状態から履歴の要求を開始するには (たとえば、部屋を開いたり再開したりするとき)、履歴要求の前に
room.initHistory();
を呼び出す必要があります。
コンテンツ マネージャー
Matrix ホームサーバーでは、コンテンツ (画像、動画、ファイルなど) のダウンロードおよびアップロードを行うためのコンテンツ API が提供されています。コンテンツ マネージャーは、その API のラッパーを提供します。
session.getContentManager();
指定されたセッションに関連付けられたコンテンツ マネージャーを検索します。
コンテンツをダウンロードする
ホームサーバーによってホストされるコンテンツは、mxc スキームの URI (mxc://matrix.org/xxxx など) で識別できます (イベント、アバター URL などで使用されます)。コンテンツを取得するための基礎となる HTTP URI を取得するには、
contentManager.getDownloadableUrl(contentUrl);
ここで contentUrl は mxc:// content URL です。
画像については、フルサイズの画像の代わりにサムネイルを返す追加メソッドが存在します。
contentManager.getDownloadableThumbnailUrl(contentUrl, width, height, method);
これにより特定の幅、高さおよびスケール方法 (scale と cropの間) が要求されるようになります。
コンテンツをアップロードする
ファイルからコンテンツをアップロードするには、
contentManager.uploadContent(filePath, callback);
ファイル パスとコールバック メソッドを指定し、完了時にアップロード コンテンツが見つかった mxc-style URI を含むオブジェクトが返されるようにします。