リクエストのライフサイクル
次の手順は、Brightcove Recommendations が有効な状態での再生セッション中に何が起こるかを示しています。
- 動画の再生が開始される — プレーヤーが Recommendations サービスにレコメンデーションを要求します。通常の
video_viewイベントが記録されます。 - レコメンデーションが表示される — レコメンドスレートが(タイミング設定に基づいて)表示されます。スレート内に表示されたレコメンド動画ごとに
recommendation_impressionイベントが記録されるため、複数の動画を表示するスレートは複数のインプレッションとしてカウントされます。初回動画は視聴済みとして登録されます。 - カウントダウンが始まる — 自動再生が有効な場合、カウントダウンタイマーが開始します。次のレコメンド動画が事前に取得されます。
- レコメンド動画が再生される —
source_video_idに初回動画の ID を設定した新しいvideo_viewが記録されます。プレーヤーは(現在の動画ではなく)初回動画に基づいて次のレコメンデーションセットを要求します。視聴済みの動画は除外されます。 - サイクルが続く — 以降のレコメンデーションごとに手順 2〜4 が繰り返されます。すべてのリクエストは初回動画に固定されたままです。
アルゴリズム
Brightcove Recommendations には 3 つのレコメンデーション戦略があります。それぞれ異なる主要シグナルを使用しますが、すべて同じ対象条件と制約ルールが適用されます。
Related Content(関連コンテンツ)
AI ベースの類似度を主要なランキングシグナルとして、セマンティックに類似したコンテンツを見つけます。システムは動画のメタデータを分析し、カタログ内で最も密接に関連するコンテンツを特定します。
2 つのブースターが結果を精緻化します。
- タグの類似度 — 重複するタグを持つ動画を優先し、メタデータが適切に構造化されている場合に精度を向上させます。
- 新しさブースター — 新しいコンテンツをわずかに優先し、定番の一致に加えて新しい動画も表示されるようにします。
Trending Now(トレンド)
複数のシグナルを組み合わせて、バイラルで人気のあるコンテンツを特定します。
- 人気スコア — 設定された期間(日次または週次)内の総動画視聴回数に基づきます。
- 勢いスコア — 動画視聴の加速度を測定し、急速に注目を集めているコンテンツを特定します。
- 時間減衰 — 古い急上昇よりも最近トレンドになっているコンテンツを優先します。
トレンドスコアを計算した後、関連性を維持するために、初回動画とのセマンティック類似度とタグの一致で再スコアリングされます。
Recently Added(最近追加)
公開日(新しい順)で動画を並べ替えて、最新の公開コンテンツを表示します。その後、最も関連性の高い新しいコンテンツが上位になるように、初回動画とのセマンティック類似度とタグの一致で再スコアリングされます。
重複排除
プレーヤーは、セッション中に既に表示された動画を自動的に追跡し、今後のレコメンデーションから除外します。ソース動画自体もそのレコメンデーションから除外されます。
プレーヤーの状態がリセットされると(ページの更新など)、追跡もリセットされ、以前に表示された動画が再び表示される場合があります。
フォールバック戦略
Admin モジュールで Expand Recommendations 設定が有効になっていて、結果が見つからない場合:
- システムは、ルックバック期間と再生時間の制約なしでクエリを再試行します。
- フォールバック中も制約は引き続き適用され、緩和されることはありません。
これにより、編集上のガードレールを尊重しながら、レコメンドスレートが空にならないようにします。
Recommendations API
プレーヤープラグインに加えて、Recommendations API を介してプログラムでレコメンデーションにアクセスし、レール、カルーセル、発見ページなどのカスタム UX 要素を構築できます。
ベース URL
https://recommendations.api.brightcove.com
認証
Recommendations API は Brightcove OAuth を使用します。Authorization ヘッダーに Bearer トークンを含めてください。必要な権限はエンドポイントによって異なります。
Authorization: Bearer {access_token}
| エンドポイント | 権限 |
|---|---|
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 つの制約が必要です。