パーソナライゼーション

StoryHubフィードは、各ユーザーの興味やコンテキストに合わせた AI パーソナライズコンテンツを配信します。

仕組み

フィード API は2段階のアプローチを使用します:

検索（Retrieval） — セマンティック検索により、ユーザーのプロフィールとコンテキストに関連するコンテンツを取得します。
ランキング（Ranking） — コンテンツをランク付けし、関連性・鮮度・多様性のバランスを取ります。

パーソナライゼーションの向上

ユーザーイベントの送信

最も効果的なアクションは、エンゲージメントイベントを送信することです。クリックイベントにより、ユーザーが何に興味を持っているかをシステムに伝えます:

POST /v1/events
{
  "events": [
    {
      "type": "click",
      "session_id": "...",
      "tracking_token": "...",
      "occurred_at": "..."
    }
  ]
}

ユーザープロパティの登録

より精度の高いレコメンデーションのために、ユーザーのコンテキスト情報を提供してください:

PUT /v1/users/{user_id}
{
  "properties": {
    "area_names": ["渋谷"],
    "area_level": "station"
  }
}

エリアコンテキストの活用

ロケーションコンテキストを渡すことで、地域に関連するコンテンツをブーストできます:

GET /v1/feed?scenario=YOUR_SCENARIO_NAME&area_names=渋谷&area_level=station

area_level は「どの階層のエリアをブーストしたいか」を指定するパラメーターです。指定したレベルで各エリア名の解決を試み、見つからない場合は他のレベルにフォールバックします。省略した場合は station → city → prefecture の順で解決されます（例: area_names=渋谷 は 渋谷駅 に解決されます）。

area_level の選択肢:

値	解決レベル
`station`	駅
`city`	市区町村
`prefecture`	都道府県

エリア名の接尾辞は省略可能です。レベルごとに以下のように正規化されます:

レベル	接尾辞	例
`station`	駅	`渋谷` ⇔ `渋谷駅`
`city`	市・区・町・村	`座間` ⇔ `座間市`
`prefecture`	都・道・府・県	`神奈川` ⇔ `神奈川県`

複数の area_names を併記した場合、area_level より上位のレベルで解決された名前は直接ブーストされませんが、同名エリアの絞り込みに使われます。たとえば area_names=横浜市,藤が丘&area_level=station を指定すると、横浜市 は文脈情報として扱われ、複数の都市に存在しうる 藤が丘 のうち横浜市内の駅が選ばれます。

日本語エリア名の URL エンコード

area_names に日本語の駅名を指定する場合、URL エンコード（パーセントエンコード）が必要です。エンコードされていない場合、400 Bad Request が返されます。curl を使用する場合は --data-urlencode オプションが便利です。詳しくはよくある質問をご覧ください。

未登録のエリア名が含まれている場合、そのエリアはスキップされます（エラーにはなりません）。
ブースト対象になる名前が1件も解決されなかった場合、文脈として渡した名前がブースト対象に切り替わります（例: area_names=座間市&area_level=station は 座間市 をブーストします）。

エリア解決の優先順位:

明示的な area_names クエリパラメーター（最優先）
ユーザープロフィールに登録されたエリア
エリアコンテキストなし（エリアブースト無効）

解決結果の確認

area_names を明示的に指定した場合、またはユーザープロフィールから自動適用された場合、GET /v1/feed のレスポンスに meta.resolved_areas が含まれ、各エリア名がどう解決されたかを確認できます。

"resolved_areas": [
  { "name": "藤が丘", "status": "resolved", "role": "target",  "area_id": "...", "area_name": "藤が丘駅", "area_level": "station", "parent_name": "横浜市" },
  { "name": "横浜市", "status": "resolved", "role": "context", "area_id": "...", "area_name": "横浜市",   "area_level": "city",    "parent_name": "神奈川県" },
  { "name": "港",     "status": "skipped",  "reason": "not_found" }
]

role は、ブースト対象になった (target)、同名エリアの絞り込みに使われた (context)、文脈からブースト対象に格上げされた (promoted) のいずれかを示します（status が resolved の場合のみ）。
status が skipped の場合、reason は not_found（該当するエリアがない）または out_of_scope（同名候補は存在するが、いずれもエリアスコープの範囲外だった）のいずれかになります。
同名のエリアが複数マッチしたまま保持された場合、同じ name で複数エントリが返ります。

同名の駅やエリアが存在しうる地域密着型のサービスでは、StoryHubフィード管理画面のチーム設定で「エリアスコープ」を登録しておくことを推奨します。全国展開などでエリアスコープを一つに絞れない場合は、area_names に上位のエリア名（市区町村・都道府県）を併記することでも同様に絞り込めます。

未登録ユーザーの挙動

ユーザーの事前登録状況に応じて、フィードの挙動が異なります：

条件	フィードの挙動
`PUT /v1/users/{user_id}` で登録済み	パーソナライズされたフィードを返却
未登録の `user_id` を指定	汎用フィードを返却（パーソナライズなし）
`user_id` を指定しない	匿名の汎用フィードを返却

GET /v1/feed ではユーザーの自動作成は行われません。
未登録ユーザーでも area_names を指定すればエリアに最適化されたフィードが返却されます。
ユーザーの作成方法についてはユーザー管理をご覧ください。

フィードの多様化

API は自動的に結果を多様化し、特定のソースやカテゴリーがフィードを独占することを防ぎます。これにより、ユーザーにバランスの取れたコンテンツ体験を提供します。

シナリオ

コンテンツ配信は、ランキングの挙動を制御するシナリオを通じて設定されます。シナリオには以下の2つのタイプがあります:

フィード — アプリ内でコンテンツフィードを表示するためのシナリオ（例: ホーム画面のメインフィード、カテゴリー別フィードなど）
プッシュ — プッシュ通知の候補コンテンツを選定するためのシナリオ

シナリオ名はテナントごとに自由に定義できます。StoryHubフィード管理画面からシナリオを作成し、アルゴリズムと紐づけて利用してください。設定の詳細については、担当のアカウントマネージャーにお問い合わせください。

仕組み​

パーソナライゼーションの向上​

ユーザーイベントの送信​

ユーザープロパティの登録​

エリアコンテキストの活用​

解決結果の確認​

未登録ユーザーの挙動​

フィードの多様化​

シナリオ​

仕組み