はじめに

このガイドでは、StoryHubフィード API をアプリケーションに統合する手順を説明します。

前提条件

1. テナントアカウント — 担当のアカウントマネージャーが作成したアカウントで StoryHubフィード管理画面 にログインしてください。
2. API Key — StoryHubフィード管理画面から API Key（shf_...）を発行してください。
3. クレジット — ご契約プランに応じたクレジットが付与されています。

用語について

テナント、シナリオ、アルゴリズム等の用語については 用語集 をご覧ください。

クイックスタート

1. シナリオとアルゴリズムを設定する

StoryHubフィード管理画面でシナリオとアルゴリズムを設定してください。シナリオはコンテンツ配信の用途（フィード表示、プッシュ通知など）を定義し、アルゴリズムはランキングの挙動を制御します。

設定の詳細については、担当のアカウントマネージャーにお問い合わせください。

2. コンテンツフィードを取得する

curl -G "https://api.feed.storyhub.studio/v1/feed" \
  --data-urlencode "scenario=YOUR_SCENARIO_NAME" \
  --data-urlencode "user_id=user-12345" \
  --data-urlencode "area_names=渋谷" \
  --data-urlencode "area_level=station" \
  --data-urlencode "limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

パラメーター	必須	説明
scenario	必須	管理画面で定義したシナリオコード
user_id	推奨	アプリ側のユーザー ID。パーソナライズに使用
area_names	推奨	エリア名（カンマ区切り）。エリアブーストに使用
area_level	推奨	エリアの解決レベル（station / city / prefecture / country）
limit	任意	取得件数（1〜100、デフォルト 20）

全パラメーターとレスポンスの詳細は API リファレンス の GET /feed をご覧ください。

3. ページネーション

レスポンスの meta.next_cursor を次のリクエストの cursor パラメーターに渡すことで、続きのコンテンツを取得できます。next_cursor が null の場合、それ以上のコンテンツはありません。

4. ユーザーを登録する

フィード配信開始前に、アプリケーションの既存ユーザーを登録しておくことを推奨します。これにより初回フィード取得時からパーソナライゼーションが機能します。

curl -X PUT "https://api.feed.storyhub.studio/v1/users/user-12345" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "area_names": ["渋谷"],
      "area_level": "station"
    }
  }'

PUT /v1/users/{user_id} は Upsert です（存在しなければ作成、存在すれば更新）。ユーザー管理 API はすべて無料です。詳細は ユーザー管理 をご覧ください。

5. ユーザーエンゲージメントをトラッキングする

ユーザーの行動イベントを送信することで、パーソナライゼーションの精度が向上します：

curl -X POST "https://api.feed.storyhub.studio/v1/events" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "click",
        "session_id": "YOUR_SESSION_ID",
        "user_id": "user-12345",
        "tracking_token": "eyJ... (from feed response)",
        "occurred_at": "2025-01-15T10:00:00Z"
      }
    ]
  }'

イベント種別や推奨する送信パターンについては 行動イベント をご覧ください。

実装チェックリスト

• API Key をサーバーサイドで管理し、クライアントに露出させない
• フィード取得時に user_id / area_names / area_level を適切に設定
• 行動イベント（session_start、login、click、impression）を送信
• エラー・レートリミット（429）に対するリトライ処理を実装
• ページネーション（next_cursor）を利用した無限スクロールの実装

次のステップ

• 用語集 — 主要な用語の定義
• 認証 — API Key の管理とローテーション
• 行動イベント — イベント種別と送信パターン
• API リファレンス — エンドポイントの詳細ドキュメント
• クレジット使用量 — クレジットモデルの説明