ピン留めプラグイン（別名「Picture-in-Picture Plugin」または「pinned」）

概要

Pinning モードを使用すると、ユーザーはマルチタスクを行えるようになります。動画再生が開始された後、ユーザーがページを下にスクロールすると、Pinning モードはプレーヤーをウェブページの隅に再配置してピン留めします。

なぜ Pinning と呼ばれるのか

このプラグインで有効になる動作は、一般的に「フローティング」や「ピン留め」とも呼ばれます。Brightcove では「Pinning」という用語を使用しています。その理由は次のとおりです:

• Apple および Google がそれぞれのネイティブブラウザでこの用語を採用しています。
• W3C の標準でも「Pinning」が参照されています。

Brightcove プラグインとネイティブ機能の比較

最近のほとんどのブラウザは Pinning 機能を内蔵しています。このセクションでは、Pinning プラグインとネイティブ機能との違いを説明します。続いて、ネイティブ機能をオフにしてプレーヤーにこのプラグインを追加したい理由について説明します。

ブラウザのネイティブ機能

ブラウザのネイティブ Pinning 機能の動作の詳細は次のとおりです:

• 機能を有効にするために何もする必要はなく、Pinning のアイコンがコントロールバーに表示されます。
• このアイコンボタンはトグルとして動作し、視聴者は機能のオン／オフを切り替えます。
• ネイティブの Pinning 機能は、まったく新しいブラウザ／OS のウィンドウでブラウザのプレーヤーを開きます。これは起動元のウェブページから独立して制御できます。そのため、Pinning プレーヤーはブラウザの境界に縛られません。Pinning プレーヤーは、ブラウザのサイズに関わらず、画面の右下に表示されます。
• ネイティブ Pinning 機能がオンに切り替えられると、Brightcove Player 内の動画は「グレーアウト」されます。
• 広告が有効になっているとき、ネイティブの Pinning ボタンは表示されません。

動作の確認

ネイティブ実装の使用例については、こちらの動画をご覧ください:

機能をオフにする

ブラウザのネイティブ機能をオフにしたい場合は、Video Cloud Studio の JSON Editor を使用して、プレーヤー設定に次の JSON コード行を配置します:

"picture_in_picture_control": false,

Brightcove プラグイン

Brightcove Player の Pinning プラグインの動作の詳細は次のとおりです:

• プラグインがインストールされたら、視聴者は Brightcove Player のほとんどを画面外にスクロールするだけで Pinning プレーヤーを開始できます。Pinning をオンにするためにクリックするボタンはありません。
• 視聴者が Brightcove Player を再び画面内にスクロールすると、Pinning プレーヤーは自動的に消えます。
• Pinning プレーヤーは（デフォルトで）ブラウザの右下に表示されます。ネイティブ機能とは異なり、このプラグインはブラウザの境界に縛られます。

動作の確認

Brightcove Player プラグイン実装の使用例については、こちらの動画をご覧ください:

なぜ Brightcove Player プラグインを使用するのか?

ネイティブ機能が組み込まれていて何もする必要がないのに、なぜネイティブ機能をオフにして Brightcove Player プラグインをインストールしたいのでしょうか? 以下にその理由をいくつか挙げます:

• ネイティブのプレーヤーはクライアントサイド広告を再生しません。SSAI 広告は再生しますが、Brightcove Player のような UI のカスタマイズは提供されず、ユーザーが広告をシーク／飛ばすことを防止しません。
• Pinning 機能をブラウザの境界内に収めたい場合。Pinning プレーヤーをブラウザのスペース外に配置したくない場合。
• ユーザーの操作なしで機能を有効にしたい場合。
• プラグインはより多くの、また実装が容易なカスタマイズを提供します。プラグインで使用できるオプション、メソッド、イベントは、このドキュメントの末尾近くに記載されています。

プレーヤーの例

動画の再生を開始します。（その後、停止することもできます。）ページを下にスクロールすると、ウェブページの右隅に Pinning プレーヤーが表示されます。Pinning プレーヤーを閉じるか、上にスクロールしてフルサイズのプレーヤーに戻ることができます。

See the Pen Pinning Plugin by Brightcove Learning Services (@bcls1969) on CodePen.

Players モジュールを使用した実装

Players モジュールを使用して Pinning プラグインを実装するには、次の手順に従います:

1. PLAYERS モジュールを開き、新しいプレーヤーを作成するか、プラグインを追加したいプレーヤーを見つけます。
2. そのプレーヤーへのリンクを選択して、プレーヤーのプロパティを開きます。
3. Overview タブの Plugins セクションを展開します。

4. 次に、Add Plugin ボタンを選択して、Brightcove Plugin を選択します。

   

5. Brightcove Plugin ドロップダウンを展開して、Pinning を選択します。

   

6. オプション: Options(JSON) テキストボックスに設定オプションを入力します。プレーヤーが Pinning モードのときの水平方向の配置を設定する例を以下に示します:

   

   詳細については、オプションセクションを参照してください。

7. Add ボタンを選択します。

8. プレーヤーのプラグインリストに Pinning プラグインが追加されたことが確認できます。

9. プレーヤーを公開するには、Publish Changes を選択します。
10. 開いているダイアログを閉じるには、Close を選択します。

11. MEDIA モジュールに戻り、Pinning 用に更新したばかりのプレーヤーを使用して動画を公開します。

12. エディターで、プレーヤーの埋め込みコードをウェブページにコピーします。

13. Pinning プラグインでは、プレーヤーがクラスが vjs-pinning-container に設定されたコンテナ要素でラップされている必要があります。コードは次のようになります:

    <div class="vjs-pinning-container">
      <video-js id="myPlayerID"
        data-video-id="5701202551001"
        data-account="1752604059001"
        data-player="default"
        data-embed="default"
        width="640" height="360"
        controls=""></video-js>
      <script src="https://players.brightcove.net/1752604059001/default_default/index.min.js"></script>
    </div>

    上記の <div> 要素がプレーヤーの親として見つからない場合、プラグインの初期化に失敗し、次のログ警告が表示されます:

    VIDEOJS: WARN: expected player to be a child of a "vjs-pinning-container" element, cannot continue with Pinning plugin

14. 動画の再生が開始されたら、下にスクロールして Pinning プレーヤーがページの下部にピン留めされる様子を確認します。

JSON Editor を使用した実装

プレーヤー 7.21.0 以降では、JSON Editor を使用して次の手順でプラグインを追加することもできます:

Players モジュールで、設定したいプレーヤーに移動します。Overview タブの JSON Editor セクションを展開します。 "plugins" 配列を変更して、Pinning プラグインを追加します。

  
    "plugins": [
    {
      "name": "pinning",
      "is_packaged": true,
      "options": {
        ...
      }
    }
  ]

オプション

初期化時にオプションオブジェクトをプラグインに渡すことができます。このオブジェクトには次のいずれかのオプションを含めることができます:

allowOnMobile

• allowOnMobile:
  • 型: boolean
  • デフォルト: false

  • デフォルトでは、Pinning モードは Android または iOS のモバイルデバイスでは動作しません。これは、これらの CSS の固定配置が、複数のビューポートを持つズーム可能なデバイスではデスクトップデバイスと同じようには動作しないためです。

    サポートされているモバイルデバイスで Pinning を有効にしたい場合は、このオプションで有効化できます。サポートを有効にしたいケースには次のようなものがあります:

    • インテグレーターが Pinning プレーヤーモードの位置管理の責任を負うことに同意する場合。
    • そのプレーヤーを使用するウェブサイトでズームされる可能性が低い場合。
    • user-scalable=no ディレクティブを使用してズームが無効化されている場合。このディレクティブを使用すると、position: fixed はデスクトップと同じように動作しますが、アクセシビリティ上の懸念があるため、特に推奨はしません。

      <meta name="viewport" content="width=device-width, user-scalable=no">

  • 例:

    // Allow mobile (iOS and Android) devices to enter PIP mode.
    player.pinning({allowOnMobile: true});

closeable

• closeable:
  • 型: boolean
  • デフォルト: true
  • デフォルトでは、ユーザーがプレーヤーの右上にある X ボタンをクリックすることで、Pinning モードを無効化できます。このオプションに false を渡すことで、この機能を無効にできます。

  • 例:

    // Do not allow the user to close the PIP mode player.
    player.pinning({closeable: false});

scale

• scale:
  • 型: number
  • デフォルト: 2 / 3
  • プレーヤーが Pinning モードのときに適用されるスケーリング係数です。この値は 0 より大きく、1 以下の数値である必要があります。

  • 例:

    // Detach the player, but do not change its size.
    player.pinning({scale: 1});

  • 例 2:

    // Detach the player, and change its size to 1/2.
    player.pinning({scale: 0.5});

height および width

• height および width:
  • 型: number
  • デフォルト: null

  • デフォルトでは、プラグインは scale オプションによって決定される係数でプレーヤーの寸法を縮小します。ただし、height（または width）を指定すると、デフォルトのスケーリングを上書きして、縮小されたプレーヤーのサイズを明示的に設定します。

    1 つの寸法のみ指定された場合、もう一方はアスペクト比を維持するために縮小されます。両方の寸法が指定された場合、プレーヤーは指定された正確なサイズに設定され、アスペクト比の変更が可能になります。

  • 例:

    // Detach the player and set its width to 300 pixels. Scale its height to
    // maintain its current aspect ratio.
    player.pinning({width: 300});

posX

• posX:
  • 型: string
  • デフォルト: "right"

  • プレーヤーが Pinning モードのときの水平方向の配置です - 「right」または「left」のいずれかです。

  • 例:

    // When the player is in PIP mode, align it to the left side of the viewport.
    player.pinning({posX: 'left'});

posY

• posY:
  • 型: string
  • デフォルト: "bottom"

  • プレーヤーが Pinning モードのときの垂直方向の配置です - 「top」または「bottom」のいずれかです。

  • 例:

    // When the player is in PIP mode, align it to the top of the viewport.
    player.pinning({posY: 'top'});

viewable

• viewable:
  • 型: number
  • デフォルト: 0.8

  • プレーヤーが視認可能とみなされる閾値です。言い換えると、プレーヤーの全領域（高さおよび幅）のうちこの割合がブラウザのビューポート内に表示されているとき、視認可能とみなされます。

    例えば、デフォルトの 0.8 では、プレーヤーの 80% がビューポート内に表示されていない限り、視認可能とはみなされません。viewable の値は 0 以上 1 以下の数値である必要があります。

  • 例:

    // If more than half the player is outside of the viewport, activate PIP mode.
    player.pinning({viewable: 0.5});

manualContainerSize

• manualContainerSize:
  • 型: boolean
  • デフォルト: false

  • デフォルトでは、このプラグインを有効にしたプレーヤーは、特別なコンテナ要素の物理的な寸法をプレーヤーの寸法と同期させ続けます。ただし、この動作はすべてのユースケースで機能するとは限らないため、このオプションを true に設定することで無効化できます。

    そのようにすると、コンテナ要素は通常のブロック要素のように動作します。これは、プラグインの利用者が自分でそのサイズを管理する必要があることを意味します。

    このオプションは、コンテナの真偽値属性 data-manual-container-size を使用して埋め込みコード内で設定することもできます。この属性が存在すると、このオプションが true に設定されます。プラグインに渡された値は、埋め込みコードで定義された値より優先される点に注意してください。

  • 例:

    // Implementation will handle sizing the container.
    player.pinning({manualContainerSize: true});

  • コンテナの data-manual-container-size 属性を使用する例:

    <div class="vjs-pinning-container" data-manual-container-size>
      <video-js class="video-js vjs-default-skin">
      </video-js>
    </div>

オプションの使用

オプションを利用する方法は 2 つあります:

1. Studio の PLAYERS > PLUGINS セクション内。
2. プレーヤーで JavaScript を使用する。

Studio の使用

Studio でプレーヤーを編集し、Plugins セクションに戻ります。名前リストの Pinning をクリックします。適切な JSON 形式で、オプション（引用符で囲んで）を記載し、続けて適切な値を記述します。値が文字列の場合は引用符で囲む必要があります。数値や真偽値の場合は引用符を含めることはできません。

JavaScript の使用

コードでオプションを実装するには、オブジェクトを作成し、必要なオプションにそれぞれの値を割り当て、プラグインを呼び出す際にそのオプションオブジェクトを渡します:

videojs.getPlayer('myPlayerID').ready(function() {
  // When the player is ready, get a reference to it
  var myPlayer = this,
      options = {};

  options.scale = 0.5;
  options.posX = "left";
  // Initialize the pinning plugin
  myPlayer.pinning(options);
});

メソッド

次のメソッドを使用して Pinning プラグインを操作できます:

イベント

Pinning プラグインから次のイベントが発火されます:

変更履歴

v2.0.0 までの過去のリリースノートおよび変更履歴については、Pinning Plugin Releases を参照してください。

v2.0.0 以降に行われた重要な変更は、Brightcove Player リリースノートに記載されます。