メインコンテンツまでスキップ

プッシュ候補

非同期 API を通じて、ユーザーごとにパーソナライズされたプッシュ通知候補を生成します。

概要​

  1. POST /v1/push-candidates でジョブを送信します。
  2. API が候補を非同期で処理し、job_id を返します。
  3. GET /v1/push-candidates/{job_id} でステータスをポーリングするか、完了時に Webhook を受信します。
  4. 署名付き URL から JSONL 結果ファイルをダウンロードします。

ジョブの作成​

curl -X POST "https://api.feed.storyhub.studio/v1/push-candidates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "push_morning",
    "candidates_per_user": 3
  }'

candidates_per_user は 1 ユーザーあたりに生成される候補記事数です（デフォルト: 1、最大: 3）。

レスポンス:

{
  "job_id": "job-uuid",
  "status": "pending"
}

ジョブステータスの確認​

GET /v1/push-candidates/{job_id}
ステータス意味
pendingジョブはキューに入っています
processingジョブは実行中です
completed結果の準備が完了しました — download_url が提供されます
failedジョブが失敗しました — error フィールドを確認してください

完了すると、レスポンスに download_url（GCS V4 署名付き URL、有効期限 1 時間）が含まれます。

ダウンロード URL の使い方

download_url は認証情報が URL のクエリパラメーターに含まれた署名付き URL です。追加の認証ヘッダーは不要で、そのまま HTTP GET でダウンロードできます。

curl -o candidates.jsonl "DOWNLOAD_URL_FROM_RESPONSE"

有効期限が切れた場合は、GET /v1/push-candidates/{job_id} を再度呼び出すと新しい URL が発行されます。

結果フォーマット（JSONL）​

ダウンロードしたファイルの各行は JSON オブジェクトです。candidates 配列はスコア降順（先頭が最もスコアの高い記事）で並びます：

{"user_id": "user-123", "candidates": [{"id": "content-uuid", "title": "...", "url": "...", "thumbnail": {"url": "...", "width": 1024, "height": 512}, "source": {"name": "..."}, "published_at": "2025-01-15T08:00:00Z", "score": 0.95, "tracking_token": "eyJ..."}]}

プッシュクリックのトラッキング​

プッシュ記事のクリックを報告する際は、JSONL 出力の tracking_token を含めてください：

POST /v1/events
{
  "events": [
    {
      "type": "click",
      "session_id": "...",
      "tracking_token": "eyJ... (from push candidates JSONL)",
      "occurred_at": "..."
    }
  ]
}

プッシュクリックをトラッキングするメリット：

  • プッシュ経由でクリックされた記事は、以降のフィードリクエストから除外されます（重複排除）。
  • クリックシグナルにより、将来のレコメンデーションが改善されます。
  • アナリティクスでプッシュ通知のエンゲージメントを測定できます。
tracking_token について

tracking_token はフィード取得（GET /v1/feed）と Push 候補ファイル（JSONL）に含まれます。一方、GET /v1/contents/{content_id}（単体取得）にはランキング文脈がないため、tracking_token は含まれません。

Webhooks​

テナントに webhook_url が設定されている場合、ジョブ完了時に通知が送信されます：

  • completed または failed ステータス時に配信されます。
  • 検証用の X-StoryHub-Signature ヘッダー（HMAC-SHA256）が含まれます。
  • ベストエフォート配信で、最大 3 回リトライされます。

制約​

制限値
テナントあたりの最大同時実行ジョブ数5
実行時間（10 万ユーザー）10 分未満
ダウンロード URL の有効期限1 時間

テスト用: manual モード​

特定のユーザーを指定して候補を生成できます。開発・テスト時に便利です。

POST /v1/push-candidates
{
  "scenario": "YOUR_PUSH_SCENARIO",
  "target_mode": "manual",
  "user_ids": ["user-12345", "user-67890"]
}

クレジット​

プッシュ候補の生成は、処理されたユーザーごとにクレジットを消費します。詳細は クレジット使用量 をご覧ください。