noellabo's tech blog

@noellaboの技術ブログ

Fedibirdの投稿参照機能(技術情報)

参照機能の技術情報

Fedibirdの参照機能について、とにかく技術情報をどこかに書いておく必要があるので、暫定でここに書き下しておきます(固定化フラグ)。

ActivityPubにおける参照

Noteのreferencesコレクションとして、Noteとして解釈できるオブジェクトを列記したものです。

https://fedibird.com/@noellabo/108127694484335642

f:id:noellabo:20220417180238p:plain

備考

  • ここでは数件インラインで表現していますが、followersやoutboxなどと同様の一般的なCollectionの記法となります。firstからnextを辿ってitemsを取得してください。
  • Fedibirdでは1投稿あたり100件に制限しています

REST APIにおける参照

投稿への参照付与

API

  • POST /api/v1/statuses
追加のパラメータ 意味
status_reference_ids[] array of string Array of local status IDs in the database.
status_reference_urls[] array of string Array of status uris.

説明

投稿本文にURLを記載すると参照として抽出されますが、パラメータとして別途参照を与えることができます。通常はサーバ内表現の投稿ID(status_reference_ids)を使うことになると思いますが、複数サーバ・複数アカウントを同時に扱えるクライアントからは、投稿URLを与えられるパラメータ(status_reference_urls)があるので、そちらの方が便利かもしれません。

投稿の一括取得

API

  • GET /api/v1/statuses
パラメータ 意味
ids[] array of string Array of local status IDs in the database.

説明

参照関連のREST応答では、Statusの内容を伴わずIDだけ列挙するものが多いので、それらを一括取得するために使います。

投稿の削除と下書きに戻す

API

  • DELETE /api/v1/statuses/:id

説明

レスポンスにstatus_reference_idsが追加されます。

この値を無視すると、再投稿時に情報が失われます。参照について特別な処理をしない場合でも、この値を保持し、投稿時に渡すようにしてください。

なお、投稿時と異なるセッションではこれらのidのエンティティが未取得の場合がありますので、投稿の一括取得のAPIを利用して未取得のidについて取得すると良いでしょう。

投稿の参照の取得

API

  • GET /api/v1/statuses/:id/context
パラメータ 意味
with_reference boolean 未指定時はfalse。指定するとreferencesを切り離して返す

説明

context APIは通常、ancestorsとdescendantsを返しますが、投稿に参照が含まれる場合、未対応クライアントの互換のためにancestorsにreferencesをミックスして返します。with_referenceパラメータをtrueにすると、ancestorsとreferencesは分離され、descendantsとあわせて3つがそれぞれ返されます。

対応クライアントを作成する場合、with_referenceパラメータをtrueに指定して、取得したreferencesを一覧するカラム等を作成し、本文中の互換リンクをクライアントのカラムに誘導するリンクへ置き換えることが期待されます。

なお、このAPIによる参照は、セルフリプライの参照をマージしたものが返されます。

投稿毎の参照は各投稿のstatus_reference_idsにローカルIDを列記する形で提供されています。

投稿を参照している投稿の一覧を取得

API

  • GET /api/v1/statuses/:id/referred_by
パラメータ 意味
id string Local ID of a status in the database.

説明

逆参照を取得します。Statusエンティティの配列を返します。

通知

API

  • POST /api/v1/push/subscription
  • GET /api/v1/push/subscription
  • PUT /api/v1/push/subscription
追加のパラメータ 意味
data[alerts][status_reference] boolean Receive status reference notifications?

説明

参照通知を購読するための追加パラメータです。

Instanceエンティティ

追加の属性 意味
configuration.status_references.max_references number 投稿ごとの最大参照数
fedibird_capabilities array of string status_referenceを含んでいれば、参照機能をサポートしている
configuration: {
  status_references: {
    max_references: 100
  }
},
fedibird_capabilities: [
  "status_reference"
],

Statusエンティティ

追加の属性 意味
status_reference_ids array of string Array of references post ids
status_references_count number How many references this post has linked.
status_referred_by_count number How many refererred by posts has linked.
{
  (snip...),
  status_reference_ids: ["108127691208762426", "108127665293086217", "108127467700309922"],
  status_references_count: 3,
  status_referred_by_count: 2
}

Notificationエンティティ

参照通知

Type属性がstatus_referenceで、status属性を伴うエンティティタイプが追加されます。status属性は参照先ではなく、リンクした元投稿となります。

『この投稿から参照されました』という意味になります。

設定値

Initial State

Initial stateとして、下記の値がWebUI向けに提供されます。

追加の属性 意味
enable_status_reference boolean 参照機能を有効にしているか(ユーザー)
match_visibility_of_references boolean フォロワー限定の参照を追加するときに、投稿の公開範囲を一致させる動作をデフォルトとするか(ユーザー)
post_reference_modal boolean 参照を含む投稿を投稿する時に確認ダイアログを表示するか(ユーザー)
add_reference_modal boolean フォロワー限定の参照を追加する時に確認ダイアログを表示するか(ユーザー)
unselect_reference_modal boolean 参照の解除時に確認ダイアログを表示するか(ユーザー)
status_references.max_references number 投稿ごとの最大参照数(サーバ)

互換機能と専用対応

[参照]リンク

本文の末尾に[参照]という投稿元サーバの参照の公開ページへのリンクが付与されます。reference-link-inlineというclassが指定されたspanタグに囲まれていますので、リモートサーバやクライアントで参照に対応する際は、このリンクを含むspanを除去し、それぞれで提供する専用のものに置き換えてください。

<span class="reference-link-inline"><a href="https://〜"> [参照]</a></span>

参照の公開ページ

参照リンクからたどれる公開ページは、投稿にリンクした参照先の投稿が、新しい順に並んで表示されます。

投稿元のサーバにログインしているユーザーは、アカウントフォロー関係やミュート・ブロック関係に基づき、表示可能な投稿、非表示にする投稿が選択されます。

ログインしていない場合は、フォロワー限定の投稿は表示されませんが、ミュートやブロックは未指定となるため、意図しない投稿者の投稿がみえる場合があります。

様々な条件で、表示対象が一件もない場合、投稿が存在しないエラーページが表示されます。

なお、このページにapplication/activity+jsonをリクエストすると、referencesコレクションにリダイレクトされます。

OGPとプレビューカード

前記の公開ページはOGPにて参照の概要を提供しています。他のリンクがなければ、Mastodonはこのリンク先から取得したOGPに基づきプレビューカードを作成しますので、クライアントはこれを表示するという選択肢もあります。

f:id:noellabo:20220417201505p:plain

ただし、プレビューカードは個別の事情を反映しておらず、公開範囲やミュート・ブロックを反映することができないため、クライアントサイドでカスタム表示した方がより優れた表示が可能となります。

セルフリプライと参照

セルフリプライは同じ投稿者が自身の投稿にリプライしたもので、通常のリプライとしての扱いではなく、Mastodonによって起点となる投稿と同等の扱いを受けるという特徴があります。

本参照機能では、セルフリプライによる一連のスレッドで参照を共有(マージ)します。このことにより、参照は追記が可能になります。context APIにて取得できるreferencesは、マージされたものが返されます。