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

概要

ピン留めモードを使用すると、ユーザーはマルチタスクを行うことができます。動画の再生が開始された後、ユーザーがページを下にスクロールすると、ピン留めモードによってプレーヤーの位置が変更され、Web ページの隅に固定表示されます。

ピン留めと呼ばれる理由

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

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

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

現在、ほとんどのモダン ブラウザにはピン留め機能が組み込まれています。このセクションでは、ピン留めプラグインとネイティブ機能の違いを説明します。続いて、ネイティブ機能を無効にしてプレーヤーにプラグインを追加したくなる理由について説明します。

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

以下は、ブラウザに標準搭載されているピン留め機能の動作についての説明です。

• 機能を有効にするために特別な設定は不要で、ピン留め用のアイコンがコントロールバーに表示されます。
• アイコン ボタンはトグルとして機能し、視聴者はオン／オフを切り替えることができます。
• ネイティブのピン留め機能は、まったく新しいブラウザ／OS ウィンドウでブラウザ プレーヤーを開き、起動元の Web ページとは独立して操作できます。そのため、ピン留めプレーヤーはブラウザの表示領域に制限されません。ブラウザのサイズに関係なく、画面の右下に表示されます。
• ネイティブのピン留め機能がオンになると、Brightcove Player 内の動画は「グレー表示」されます。
• 広告が有効な場合、ネイティブのピン留めボタンは表示されません。

動作の確認

以下の動画で、ネイティブ実装がどのように動作するかをご確認ください。

機能を無効にする

ブラウザのネイティブ機能を無効にしたい場合は、Video Cloud Studio の JSON エディタ を使用して、プレーヤー設定に次の JSON コード行を追加してください。

"picture_in_picture_control": false,

Brightcove プラグイン

以下は、Brightcove Player のピン留めプラグインの動作についての説明です。

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

動作の確認

以下の動画で、Brightcove Player プラグインの実装がどのように動作するかをご確認ください。

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

ネイティブ機能が組み込まれており、特に何もしなくても利用できるにもかかわらず、なぜネイティブ機能を無効にして Brightcove Player プラグインをインストールする必要があるのでしょうか。以下は、その主な理由です。

• ネイティブ プレーヤーはクライアントサイド広告を再生しません。SSAI 広告は再生されますが、Brightcove Player が提供するような UI のカスタマイズはできず、ユーザーが広告をシークしてスキップすることを防ぐこともできません。
• ピン留め機能をブラウザの表示領域内に制限したい場合です。ピン留めプレーヤーをブラウザの外に表示させたくない場合に有効です。
• ユーザーの操作なしで機能を有効にしたい場合です。
• このプラグインでは、より多くのカスタマイズが可能で、実装も容易です。プラグインで使用できるオプション、メソッド、イベントについては、本ドキュメントの後半に一覧があります。

プレーヤーの例

動画の再生を開始してください（その後、停止してもかまいません）。ページを下にスクロールすると、Web ページ右下にピン留めプレーヤーが表示されます。ピン留めプレーヤーを閉じるか、ページを上にスクロールして元のフルサイズのプレーヤーに戻すことができます。

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

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

Players モジュールを使用してピン留めプラグインを実装するには、次の手順に従ってください。

1. PLAYERS モジュールを開き、新しいプレーヤーを作成するか、プラグインを追加したい既存のプレーヤーを選択します。
2. 対象のプレーヤーのリンクを選択して、プレーヤーのプロパティを開きます。
3. 左側のナビゲーションメニューから プラグイン を選択します。

4. 次に、プラグインの追加 ボタンを選択し、Brightcove プラグイン を選択します。

   

5. Brightcove プラグイン のドロップダウンを展開し、Pinning を選択します。

   

6. 任意: オプション(JSON) テキストボックスに設定オプションを入力します。ここでは、ピン留めモード時のプレーヤーの水平方向の配置を設定する例を示しています。

   

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

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

8. これで、プレーヤーのプラグイン一覧に Pinning プラグインが追加されていることを確認できます。

9. プレーヤーを公開するには、公開と埋め込み > 変更の公開 を選択します。
10. 開いているダイアログを閉じるには、閉じる を選択します。

11. MEDIA モジュールに戻り、ピン留め用に更新したプレーヤーを使用して動画を公開します。

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

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. 動画の再生が開始されたら、ページを下にスクロールして、ページ下部にピン留めされるピン留めプレーヤーを確認します。

JSON エディタを使用した実装

プレーヤー 7.21.0 以降では、JSON エディタを使用してプラグインを追加する場合も、次の手順に従ってください。

Players モジュールで設定したいプレーヤーに移動し、JSON エディタのリンクをクリックします。 "plugins" 配列を変更して、ピン留めプラグインを追加します。

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

オプション

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

allowOnMobile

• allowOnMobile:
  • タイプ: boolean
  • デフォルト: false

  • デフォルトでは、ピン留めモードは Android または iOS のモバイル デバイスでは動作しません。これは、複数のビューポートを持ち拡大縮小可能なデバイスでは、CSS の fixed 位置指定がデスクトップと同じようには動作しないためです。

    サポート対象のモバイル デバイスでピン留めを有効にしたい場合は、このオプションで設定できます。サポートを有効にしたくなるケースとしては、次のようなものがあります。

    • 実装担当者が、ピン留めプレーヤーモードの配置管理を担う意思がある場合。
    • プレーヤーを使用する Web サイトで拡大縮小が行われる可能性が低い場合。
    • user-scalable=no ディレクティブを使用して拡大縮小を無効にしている場合。このディレクティブを使用すると、position: fixed がデスクトップと同様に動作しますが、アクセシビリティ上の懸念となる可能性があるため、特に推奨されるものではありません。

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

  • 例:

    // モバイル（iOS および Android）デバイスで PIP モードへの移行を許可します。
    player.pinning({allowOnMobile: true});

closeable

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

  • 例:

    // ユーザーが PIP モードのプレーヤーを閉じられないようにします。
    player.pinning({closeable: false});

scale

• scale:
  • タイプ: number
  • デフォルト: 2 / 3
  • ピン留めモード時にプレーヤーに適用される拡大縮小率です。この値は 0 より大きく、1 以下の数値である必要があります。

  • 例:

    // プレーヤーを切り離しますが、サイズは変更しません。
    player.pinning({scale: 1});

  • 例 2:

    // プレーヤーを切り離し、サイズを 1/2 に変更します。
    player.pinning({scale: 0.5});

height and width

• height と width:
  • タイプ: number
  • デフォルト: null

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

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

  • 例:

    // プレーヤーを切り離し、幅を 300 ピクセルに設定します。高さは
    // 現在のアスペクト比を維持するようにスケールします。
    player.pinning({width: 300});

posX

• posX:
  • タイプ: string
  • デフォルト: "right"

  • ピン留めモード時のプレーヤーの水平方向の配置です。"right" または "left" を指定します。

  • 例:

    // プレーヤーが PIP モードのとき、ビューポートの左側に配置します。
    player.pinning({posX: 'left'});

posY

• posY:
  • タイプ: string
  • デフォルト: "bottom"

  • ピン留めモード時のプレーヤーの垂直方向の配置です。"top" または "bottom" を指定します。

  • 例:

    // プレーヤーが PIP モードのとき、ビューポートの上側に配置します。
    player.pinning({posY: 'top'});

viewable

• viewable:
  • タイプ: number
  • デフォルト: 0.8

  • プレーヤーが「表示可能」と見なされるしきい値です。つまり、プレーヤー全体の面積（高さと幅）のうち、この割合がブラウザのビューポート内に表示されている場合に表示可能と判定されます。

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

  • 例:

    // プレーヤーの半分以上がビューポート外にある場合、PIP モードを有効化します。
    player.pinning({viewable: 0.5});

manualContainerSize

• manualContainerSize:
  • タイプ: boolean
  • デフォルト: false

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

    無効化すると、コンテナ要素は通常のブロック要素のように振る舞います。つまり、プラグイン利用者がコンテナのサイズを自身で管理する必要があります。

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

  • 例:

    // 実装側でコンテナのサイズ調整を行います。
    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 > プラグイン セクションで設定する。
2. プレーヤーで JavaScript を使用する。

Studio を使用する

Studio でプレーヤーを編集し、プラグイン セクションに戻ります。名前一覧から Pinning をクリックします。正しい JSON 形式で、オプション名（引用符で囲む）と、それに対応する値を指定します。値が文字列の場合は引用符で囲む必要があります。数値または boolean の場合は、引用符を含めてはいけません。

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);
});

メソッド

次のメソッドを使用して、ピン留めプラグインを操作できます。

イベント

次のイベントは、ピン留めプラグインから発火されます。

変更履歴

v2.0.0 までの過去のリリースノートおよび変更履歴については、ピン留めプラグインのリリース一覧 を参照してください。

v2.0.0 以降の主な変更点は、Brightcove Player リリース ノート に掲載されます。