レコメンデーションの仕組み

Brightcove Recommendations がどのようにレコメンデーションを生成するか(リクエストのライフサイクル、アルゴリズム、重複排除、Recommendations API)について説明します。

リクエストのライフサイクル

次の手順は、Brightcove Recommendations が有効な状態での再生セッション中に何が起こるかを示しています。

  1. 動画の再生が開始される — プレーヤーが Recommendations サービスにレコメンデーションを要求します。通常の video_view イベントが記録されます。
  2. レコメンデーションが表示される — レコメンドスレートが(タイミング設定に基づいて)表示されます。スレート内に表示されたレコメンド動画ごとに recommendation_impression イベントが記録されるため、複数の動画を表示するスレートは複数のインプレッションとしてカウントされます。初回動画は視聴済みとして登録されます。
  3. カウントダウンが始まる — 自動再生が有効な場合、カウントダウンタイマーが開始します。次のレコメンド動画が事前に取得されます。
  4. レコメンド動画が再生される — source_video_id に初回動画の ID を設定した新しい video_view が記録されます。プレーヤーは(現在の動画ではなく)初回動画に基づいて次のレコメンデーションセットを要求します。視聴済みの動画は除外されます。
  5. サイクルが続く — 以降のレコメンデーションごとに手順 2〜4 が繰り返されます。すべてのリクエストは初回動画に固定されたままです。

アルゴリズム

Brightcove Recommendations には 3 つのレコメンデーション戦略があります。それぞれ異なる主要シグナルを使用しますが、すべて同じ対象条件と制約ルールが適用されます。

AI ベースの類似度を主要なランキングシグナルとして、セマンティックに類似したコンテンツを見つけます。システムは動画のメタデータを分析し、カタログ内で最も密接に関連するコンテンツを特定します。

2 つのブースターが結果を精緻化します。

  • タグの類似度 — 重複するタグを持つ動画を優先し、メタデータが適切に構造化されている場合に精度を向上させます。
  • 新しさブースター — 新しいコンテンツをわずかに優先し、定番の一致に加えて新しい動画も表示されるようにします。

複数のシグナルを組み合わせて、バイラルで人気のあるコンテンツを特定します。

  • 人気スコア — 設定された期間(日次または週次)内の総動画視聴回数に基づきます。
  • 勢いスコア — 動画視聴の加速度を測定し、急速に注目を集めているコンテンツを特定します。
  • 時間減衰 — 古い急上昇よりも最近トレンドになっているコンテンツを優先します。

トレンドスコアを計算した後、関連性を維持するために、初回動画とのセマンティック類似度とタグの一致で再スコアリングされます。

Recently Added(最近追加)

公開日(新しい順)で動画を並べ替えて、最新の公開コンテンツを表示します。その後、最も関連性の高い新しいコンテンツが上位になるように、初回動画とのセマンティック類似度とタグの一致で再スコアリングされます。

重複排除

プレーヤーは、セッション中に既に表示された動画を自動的に追跡し、今後のレコメンデーションから除外します。ソース動画自体もそのレコメンデーションから除外されます。

プレーヤーの状態がリセットされると(ページの更新など)、追跡もリセットされ、以前に表示された動画が再び表示される場合があります。

フォールバック戦略

Admin モジュールで Expand Recommendations 設定が有効になっていて、結果が見つからない場合:

  1. システムは、ルックバック期間と再生時間の制約なしでクエリを再試行します。
  2. フォールバック中も制約は引き続き適用され、緩和されることはありません。

これにより、編集上のガードレールを尊重しながら、レコメンドスレートが空にならないようにします。

Recommendations API

プレーヤープラグインに加えて、Recommendations API を介してプログラムでレコメンデーションにアクセスし、レール、カルーセル、発見ページなどのカスタム UX 要素を構築できます。

ベース URL

https://recommendations.api.brightcove.com

認証

Recommendations API は Brightcove OAuth を使用します。Authorization ヘッダーに Bearer トークンを含めてください。必要な権限はエンドポイントによって異なります。

Authorization: Bearer {access_token}
必要な OAuth 権限
エンドポイント 権限
GET /settings video-cloud/setting/read
POST /settings video-cloud/setting/write
POST /recommendations 有効な Brightcove OAuth トークン。特定の権限は不要です。

OAuth 認証情報の取得については、API 認証情報の管理を参照してください。

パスパラメーター

共通のパスパラメーター
パラメーター 型 必須 説明
account_id string はい Video Cloud アカウント ID。

GET /v1/accounts/{account_id}/settings

指定したアカウントのレコメンデーション設定を返します。設定が存在しない場合、API はデフォルト設定を作成して返します。

レスポンス

AccountRecommendationSettings オブジェクトを返します。全フィールドのリファレンスについては、下記の設定モデルセクションを参照してください。

例

GET /v1/accounts/1234567890/settings
Authorization: Bearer {access_token}
レスポンス例
{
  "account_id": "1234567890",
  "timeframe_days": 365,
  "max_video_duration": 1800,
  "min_video_duration": 0,
  "excluded_tags": [],
  "lock_offs": [],
  "campaigns": [],
  "trending_recurrence": "daily",
  "fallback_content": true
}

POST /v1/accounts/{account_id}/settings

指定したアカウントのレコメンデーション設定を作成または更新します。リクエストボディはパスの account_id と一致する必要があります。

リクエストボディ

ボディは AccountRecommendationSettings オブジェクトです。全フィールドのリファレンスについては、下記の設定モデルセクションを参照してください。更新したいフィールドのみを渡すことができます。

レスポンス

更新された AccountRecommendationSettings オブジェクトを返します。

エラー

エラーレスポンス
ステータス 説明
422 リクエストボディの account_id がパスパラメーターと一致しない、または検証に失敗しました。
500 設定の保存に失敗しました。

例

POST /v1/accounts/1234567890/settings
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "account_id": "1234567890",
  "timeframe_days": 180,
  "max_video_duration": 3600,
  "min_video_duration": 30,
  "excluded_tags": ["internal", "draft"],
  "trending_recurrence": "weekly",
  "fallback_content": true
}

POST /v1/accounts/{account_id}/recommendations

指定したソース動画の動画レコメンデーションを返します。このエンドポイントを使用して、Brightcove Player の外部でカスタムレコメンデーション UI 要素を構築できます。

リクエストボディ

レコメンデーションリクエストのフィールド
フィールド 型 必須 デフォルト 説明
video_id string はい — ソース動画 ID(現在再生中またはアンカー動画)。
excluded_ids array of strings いいえ null 結果から除外する動画 ID のリスト(重複排除用)。
limit integer いいえ 1 返すレコメンデーションの最大数。範囲: 1〜50。
mode string いいえ related レコメンデーション戦略: related、trending、または recent。
enable_featured_content boolean いいえ true 結果にプロモートコンテンツキャンペーンを含めるかどうか。

レスポンス

RecommendationsResponse オブジェクトを返します。

レコメンデーションレスポンスのフィールド
フィールド 型 説明
recommendations array レコメンド動画のリスト。各項目には video_id(string)と reason(string: related、trending、recent、または featured)が含まれます。
count integer 返されたレコメンデーションの数。

例

POST /v1/accounts/1234567890/recommendations
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "video_id": "6345678901234",
  "limit": 6,
  "mode": "related",
  "excluded_ids": ["6345678901111", "6345678901222"],
  "enable_featured_content": true
}
レスポンス例
{
  "recommendations": [
    {
      "video_id": "6345678901235",
      "reason": "related"
    },
    {
      "video_id": "6345678901236",
      "reason": "related"
    },
    {
      "video_id": "6345678901237",
      "reason": "featured"
    }
  ],
  "count": 3
}

設定モデル

次の表は、GET と POST の両方の設定エンドポイントで使用される AccountRecommendationSettings モデルのすべてのフィールドを説明しています。

コア設定

コアアカウント設定
フィールド 型 デフォルト 説明
account_id string — Video Cloud アカウント ID。
timeframe_days integer 365 この日数以内に公開された動画のみが対象になります。範囲: 1〜730。
max_video_duration integer | null 1800 動画の最大再生時間(秒)。null または 0 で制限なし。
min_video_duration integer | null 0 動画の最小再生時間(秒)。null または 0 で制限なし。max_video_duration を超えることはできません。
excluded_tags array of strings | null null これらのタグのいずれかを持つ動画は、すべてのレコメンデーション結果から除外されます。
trending_recurrence string daily トレンドスコアリングの期間: daily または weekly。
fallback_content boolean false true の場合、対象となる結果が少なすぎるときに、緩和されたクエリ(期間や再生時間の制限なし)にフォールバックします。制約は引き続き適用されます。

ロックオフ

ロックオフは、レコメンデーションを絞り込む編集上の制約です。ロックオフは、AND ロジックで結合される 1 つ以上の制約をまとめます。制約は、ソース動画も一致する値を持っている場合にのみ適用されます(交差ロジック)。

ロックオフのフィールド
フィールド 型 デフォルト 説明
lock_off_id string — ロックオフの一意の識別子。
name string — ロックオフの人間が読める名前。
description string | null null 任意の説明。
status string active active または archived。有効期間内の active なロックオフのみが適用されます。
start_date datetime | null null ISO 8601。ロックオフはこの日付から有効になります。
end_date datetime | null null ISO 8601。start_date より後である必要があります。
constraints array — 少なくとも 1 つの制約が必要です。単一のロックオフ内のすべての制約は同じ type を共有する必要があります。

ロックオフの制約

制約のフィールド
フィールド 型 説明
type string 制約のタイプ: tag または custom_field。
field_name string | null type が custom_field の場合に必須。照合するカスタムフィールド名。
value string レコメンド動画が一致する必要があるタグ名またはカスタムフィールド値。

プロモートコンテンツキャンペーン

キャンペーンは、プロモート動画をオーガニック結果の前にレコメンデーションカルーセルに挿入します。キャンペーン動画には reason: "featured" が割り当てられます。

キャンペーンのフィールド
フィールド 型 デフォルト 説明
campaign_id string — キャンペーンの一意の識別子。
status string active active または archived。有効期間内の active なキャンペーンのみが含まれます。
video_id string — レコメンデーションでプロモートする動画 ID。
frequency_percentage decimal — リクエストにキャンペーンが表示される確率(carousel_position が設定されていない場合)。範囲: 0.0〜100.0。
view_goal integer | null null 目標インプレッション数。この目標に達すると、キャンペーンはスキップされます。
start_date datetime — ISO 8601。キャンペーンはこの日付から有効になります。
end_date datetime — ISO 8601。start_date より後である必要があります。
carousel_position integer | null null カルーセル内の 0 始まりの位置。設定すると、ランダムな頻度ではなく、このスロットに正確に表示されます。

検証ルール

  • timeframe_days は 1〜730 の範囲である必要があります。
  • min_video_duration は max_video_duration を超えることはできません。
  • 単一のロックオフ内のすべての制約は同じ type(すべて tag またはすべて custom_field)を共有する必要があります。
  • ロックオフとキャンペーンの両方で、end_date は start_date より後である必要があります。
  • frequency_percentage は 0.0〜100.0 の範囲である必要があります。
  • 各ロックオフには少なくとも 1 つの制約が必要です。