IMA3 プラグインによる広告配信

はじめに

IMA プラグインは、Brightcove プレーヤーを Google の Interactive Media Ads (IMA) for HTML5 version 3 と連携します。これにより、プレーヤー向けに VAST、VPAID、VMAP 広告をリクエストおよびトラッキングできます。Google IMA の詳細については、Using the IMA HTML5 SDK Version 3 ドキュメントを参照してください。

PAL SDK

CSAI (クライアント サイド広告挿入) では PAL SDK は不要です。プログラマティック広告識別子は、IMA3 プラグインが使用する IMA3 SDK によって自動的に処理されます。

CCPA および GDPR への対応

CCPA (カリフォルニア州消費者プライバシー法) のサポートは、Google の IMA3 SDK によって提供されます。Google Ad Manager のインターフェイス、または広告タグ自体に "rdp=1" を指定することで、データ処理を制限できます。詳細とベスト プラクティスについては、Google のドキュメント https://support.google.com/admanager/answer/9561023 を参照してください。

GDPR (EU の一般データ保護規則) も同様にサポートされており、広告タグで "npa=1" を使用し、Google Ad Manager のインターフェイスで別の設定を行います。https://support.google.com/admanager/answer/7666366

プレーヤー サンプル

以下のサンプル動画は IMA プラグインの使用例です。動画を再生すると、プリロール、5 秒の時点でスキップ可能なミッドロール、最後にポストロールが再生されます。

広告サーバーのテスト

最初に行うべきことは、使用予定の広告タグが有効かどうかを確認することです。広告タグの URL をコピーしたうえで、次のページにアクセスしてください。 Video Suite Inspector（リンクをクリックすると新しいウィンドウまたはタブで開きます）。

広告タグの URL を Input type 入力欄に貼り付けます。Test Ad をクリックすると、Google が用意した動画と一緒に広告が再生されます。このテスト環境で広告タグが動作しない場合、Brightcove Player でも動作しません。

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

Players モジュールを使用して実装 - Advertising セクション

このセクションでは、Studio の Advertising セクションを使用して広告を実装します。この場合、フォームで提供されるオプションに限定されます。このセクションには用意されていない多くのオプションを使用してカスタマイズしたい場合は、Players モジュールを使用して実装 - Plugins セクション を参照してください。こちらでは JSON でオプションを指定できます。

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

1. Players モジュールを開き、新しいプレーヤーを作成するか、広告機能を追加したい既存のプレーヤーを選択します。
2. プレーヤーのリンクをクリックして、プレーヤーのプロパティを開きます。
3. Overview タブで Advertising アコーディオンを展開します。
4. Enable Client-Side (IMA) チェックボックスをオンにします。
5. 広告サーバーの Server URL を入力します。
6. Request Ads 設定を選択します。
   • On load - プレーヤーの読み込み時にすぐに広告がリクエストされます (通常、GAM / VPAID では最適なエクスペリエンスです)。
   • On play - 最初の広告リクエストは再生開始まで遅延します。
   • On demand - すべての広告リクエストは player.ima3.adrequest() メソッドを使用してプログラム的に開始されます。このモードはプリロールおよびポストロール広告をサポートしません。
   • On cue point - ディスパッチされた広告キュー ポイントで広告リクエストが開始されます。詳細は Displaying Ads Using Ad Cue Points ドキュメントを参照してください。
7. 広告の VPAID Mode を選択します。VPAID モードは IMA 広告で VPAID 2 のサポートを有効にするために使用します。
   • Enabled - 別ドメインの iframe で VPAID 広告を再生
   • Insecure - 同一ドメインの iframe で VPAID 広告を再生
   • Disabled - VPAID 広告はエラーをスローします
8. Timeout 値を設定します。これは、再生開始前に広告が初期化されるまで待機する最大時間 (ミリ秒) です。
9. Hard timeouts の選択を行います。このオプションをオフにすると、読み込みの遅い広告が動画再生を中断する可能性があります。
10. Maximum Number of Redirects を設定します。これは、以降のリダイレクトが拒否されて広告読み込みが中断されるまでに許容される最大リダイレクト数を指定します。リダイレクトの数は遅延に直結し、ユーザー エクスペリエンスに影響します。
11. Plugin Version には、最新バージョンを使用することを強くおすすめします。
12. 公開済みのプレーヤーに構成を反映するには、Publish Changes をクリックします。

広告プロパティへの変更が保存されると、IMA プラグインがプラグイン設定の一部として構成されます。Advertising セクションから追加したため、JavaScript と CSS は非表示になります。

IMA プラグインは、この UI セクションでは利用できない追加プロパティもサポートしています。さらに多くの構成オプションを使用する方法については、次のセクションを参照してください。

ハイブリッド実装

これまでに、Studio で IMA プラグインを実装する方法を見てきました。お客様の中には、Studio で基本的なプラグインを追加し、ページの JavaScript で構成を行うハイブリッド実装を好む方もいます。本セクションではこのハイブリッド実装について説明します。

前のセクションで見たように、IMA3 プラグインを純粋にコードで実装する場合、プラグインを関数形式で操作します。一方、Studio でプラグインをインストールしてからページで構成する場合、プラグインをオブジェクトとして扱う必要があります。たとえば、Ad Tag を指定せずに Studio で IMA3 プラグインをインストールしたとします。

このとき、ページ内の JavaScript で次のようにプロパティ値を割り当てることができます (この場合プラグインはオブジェクトとして扱います)。

videojs.getPlayer('myPlayerID').ready(function() {
  var myPlayer = this;
  myPlayer.ima3.settings.serverUrl = 'http://solutions.brightcove.com/bcls/brightcove-player/vmap/simple-vmap.xml';
});

もちろん、他のプロパティも同じ方法で値を割り当てることができます。

IMA3 プラグインと自動再生

IMA3 プラグインを介して再生される広告は、Brightcove Player に設定された自動再生構成と同様の構成を使用します (自動再生に関する考慮事項 を参照)。完全な制御が可能で、Brightcove Player のすべての自動再生値がサポートされています。

JSON と JavaScript の表記

下記の Options セクションを見ると、構成情報が JSON 形式で提供されているのが分かります。コードで IMA3 プラグインを実装する場合、JavaScript でオプションを設定する記法はわずかに異なります。

次は Studio で使用できる JSON 形式のオプションです。

{
  "requestMode": "onload",
  "serverUrl": "//solutions.brightcove.com/bcls/brightcove-player/vmap/simple-vmap.xml?cust_params={mediainfo.ad_keys}",
  "timeout": 5000
}

JavaScript でオプションを構成する場合は、JSON 形式も動作しますが、次のように JavaScript 構文を使用することもできます。

{
  requestMode: 'onload',
  serverUrl: '//solutions.brightcove.com/bcls/brightcove-player/vmap/simple-vmap',
  timeout: 5000
}

オプション

video.js IMA3 プラグインは video.js ads framework 上に構築されており、広告フレームワークが提供する任意のオプションを受け付けます。詳細は広告フレームワークの README を参照してください。本ドキュメントでは、IMA プラグイン固有のオプションと広告フレームワークのオプションの両方を取り上げます。

オプションは次のとおりです。

• clickTrackingElement
• debug
• disableCustomPlaybackForIOS10Plus
• hardTimeouts
• ima3SdkSettings
• omidAccessModeRules
• postrollTimeout
• prerollTimeout
• requestMode
• sdkurl
• serverUrl
• showVpaidControls
• timeout
• useMediaCuePoints
• vpaidMode

clickTrackingElement

型: HTMLElement
デフォルト値: undefined

HTML 広告技術が カスタム広告再生 モードで使用されている場合、このオプションは、video 要素上の入力イベントをサポートしないデバイスで広告タップを追跡するために使用する代替 HTML 要素を指定します。詳細は IMA AdDisplayContainer のパラメーター ドキュメントを参照してください。クリック トラッキング要素を指定した場合は、適切なプラットフォームと適切なタイミングでその表示・非表示を制御するのは利用者の責任です。多くの場合は、この設定を未定義のままにし、プラグインと IMA に広告操作の管理を任せるのが最良です。

debug

型: boolean
デフォルト値: false

debug を true に設定すると、再生中の広告フレームワークの状態に関する追加情報が出力されます。これは広告統合における問題や予期しない挙動の診断に役立ちます。

このオプションは広告フレームワークの一部であり、次のように構成します。

player.ima3({
  debug: true
});

次のスクリーンショットは、debug をオンにした際に表示される多数の情報の一部です。

disableCustomPlaybackForIOS10Plus

型: boolean
デフォルト値: false

このプロパティは ima3SdkSettings オブジェクトの一部です。iOS 10 以降のブラウザーでカスタム再生を無効にするかどうかを制御するゲッター/セッターとして機能します。動作は次のとおりです。

• true の場合、コンテンツ動画がインラインで再生されている場合、広告もインラインで再生され、スキップ可能広告が有効になります。ただし、広告はインラインのままで、iOS のネイティブ全画面表示はサポートされません。
• false の場合、広告はコンテンツと同じプレーヤーで再生されます。

この設定の使用例については、本ドキュメントの iOS のスキップ可能広告 セクションを参照してください。

hardTimeouts

型: boolean
デフォルト値: true

タイムアウト後に読み込みが完了した広告を破棄します。これにより、timeout が経過してコンテンツ動画の再生が始まった後で、読み込みの遅いプリロール広告が割り込むのを防ぎます。

このオプションは広告フレームワークの一部であり、次のように構成します。

player.ima3({
  hardTimeouts: true
});

このオプションを false に設定すると、広告の前にコンテンツが一瞬表示されてしまいます。

ima3SdkSettings

型: object
デフォルト値: undefined

指定されている場合、このオブジェクトのプロパティは、IMA SDK の読み込みが完了した時点でページ レベルの Ima3SdkSettings を設定するために使用されます。このオブジェクトのプロパティは、SDK 設定オブジェクトのセッター メソッドから 'set' プレフィックスを除き、キャメルケースに変換した名前である必要があります。たとえば、プラグイン初期化時に次のオブジェクトを指定したとします。

player.ima3({
  ima3SdkSettings: {
    'numRedirects': 3,
    'ppid': 'publisher-provided-id'
  }
}

すると、IMA の読み込み完了時に video.js IMA プラグインは次のようなコードを実行します。

window.google.ima.ImaSdkSettings.setNumRedirects(3);
window.google.ima.ImaSdkSettings.setPpid('publisher-provided-id');

omidAccessModeRules

型: Four access modes
デフォルト値: undefined

OM SDK では、確認スクリプトを異なるアクセス モードで実行できます。アクセス モードは、確認スクリプトがアクセスできる範囲を制御します。3 つのアクセス モードは次のとおりです。

• FULL: 確認スクリプトはクリエイティブとパブリッシャー ページに直接アクセスできます。
• DOMAIN: 確認スクリプトはサンドボックス化されており、クリエイティブやパブリッシャー ページにアクセスできません。ただし、スクリプトは、自分が読み込まれているパブリッシャー ドメインを直接確認できる方法で読み込まれます。
• LIMITED: 確認スクリプトはサンドボックス化されており、クリエイティブやパブリッシャー ページにアクセスできず、また自分が読み込まれているパブリッシャー ドメインを直接確認することもできません。

各 OmidVerificationVendor のアクセス ルールは、 omidAccessModeRules プラグイン オプションを使用して次のように設定できます。

{
  omidAccessModeRules: {
    OTHER: 'LIMITED',
    DOUBLEVERIFY: 'DOMAIN',
    GOOGLE: 'FULL'
  }
}

omidAccessModeRules を有効にするには、ima3SdkSettings 内で enableOmidBeta 機能フラグを true に設定する必要があります。次のように指定します。

{
  "featureFlags": {
    "enableOmidBeta": true
  }
}

アクセス モード ルールは ad-request レベルで設定する必要があります。確認スクリプト プロバイダーごとに異なるアクセス モードを設定するには、各 OmidVerificationVendor を上記いずれかのアクセス モードにマッピングする辞書を渡します。OmidVerificationVendor.OTHER は、辞書に明示的に含まれていないすべてのベンダーに対するデフォルトのアクセス モードを設定するために使用されます。アクセス モード ルールが指定されていない場合、確認スクリプトはベンダーに対して LIMITED アクセス モードで実行されます。

次の例では、GOOGLE を google.ima.OmidAccessMode.FULL に設定しています。OmidVerificationVendor に列挙されているものを含む他のすべてのプロバイダーは、OmidVerificationVendor.OTHER の設定によりデフォルト値が決まります。

request.omidAccessModeRules = {};
request.omidAccessModeRules[google.ima.OmidVerificationVendor.GOOGLE] = google.ima.OmidAccessMode.FULL;
request.omidAccessModeRules[google.ima.OmidVerificationVendor.OTHER] = google.ima.OmidAccessMode.DOMAIN;

postrollTimeout

型: number
デフォルト値: undefined

videojs-contrib-ads の postrollTimeout 設定を制御します。指定された場合、timeout に設定された値を上書きします。

prerollTimeout

型: number
デフォルト値: undefined

videojs-contrib-ads の prerollTimeout 設定を制御します。指定された場合、timeout に設定された値を上書きします。

requestMode

型: string
デフォルト値: onload

このオプションは広告フレームワークの一部であり、次のように構成します。

player.ima3({
  requestMode: 'onplay'
});

このオプションには 4 つの値を指定できます。

• onload: プレーヤーの読み込み時にすぐに広告がリクエストされます。通常 GAM / VPAID にとって最良のエクスペリエンスです。
• onplay: 最初の広告リクエストは再生開始まで遅延されます。これは、広告リクエストを再生とみなす広告ネットワークでは重要です。再生リクエスト前に広告リクエストが行われると、広告が最終的に減配信され、表示された広告に対して受け取る金額が少なくなることがあります。
• ondemand: player.ima3.adrequest() メソッドを手動で呼び出した場合のみ広告が再生されます。このモードはプリロールやポストロール広告をサポートしません。
• oncue: このオプションは、useMediaCuePoints オプションと併用するかどうかで挙動が異なります。

  Video Cloud でキュー ポイントを使用する

  Studio で動画に広告キュー ポイントを作成し、キュー ポイントがトリガーされたときに広告を再生できます。詳細は Display Ads Using Ad Cue Points ドキュメントを参照してください。

  ライブ ストリームでキュー ポイントを使用する

  ライブ ストリームでは、ID3 キュー ポイントに基づいて広告がリクエストされます。この種のリクエストが正しく機能するには、受信した ID3 TXXX フレームに次のフィールドを含む JSON データが必要です。

  • name: 必須。文字列値 adCue である必要があります
  • id: 必須。ライブ ストリームでは時間が相対的であるため、広告を識別する一意の値
  • serverUrl: 任意。サーバー URL に break length パラメーターとして付加されます
  • duration: 任意。広告の再生時間

  例:

  {"name": "adCue", "id": 123}

  adCue によって作成されたライブ ストリームの ID3 キュー ポイントは、adCancel を使用してキャンセルすることもできます。送信するオブジェクトは次の形式である必要があります。

  {"name": "adCancel", "id": 123}

  name と id はどちらも必須です。

  • ライブの ID3 広告キューは Android ではサポートされていません。
  • ライブの ID3 広告キャンセル キューは iOS ではサポートされていません。

sdkurl

型: string
デフォルト値:

//imasdk.googleapis.com/js/sdkloader/ima3.js

IMA SDK スクリプトへのカスタム URL を設定します。本番環境では不要ですが、デバッグ時に役立ちます。

debug が true のときは、代わりに ima3_debug.js が指定されます。

serverUrl

型: string または function
デフォルト値 (Google の汎用広告):

//pubads.g.doubleclick.net/gampad/ads?sz=400x300&iu=%2F6062%2Fiab_vast_samples&ciu_szs=300x250%2C728x90&gdfp_req=1&env=vp&output=xml_vast2&unviewed_position_start=1&url=[referrer_url]&correlator=[timestamp]&cust_params=iab_vast_samples%3Dlinear

ここでは広告サーバーへの URL を指定します。このオプションは、上記のように Brightcove Studio で構成できます。コードで値を設定することもできます。次に 2 つの例を示します (プラグインで使用する前に、サーバー上で 広告タグをテスト してください)。

値が文字列の場合、それは広告がリクエストされる広告サーバー URL を表し、コードでは次のように設定できます。

player.ima3({
  serverUrl: 'your ad server'
});

値が関数の場合、関数のパラメーターはサーバー URL を引数として呼び出すべき callback 関数です。これにより、ヘッダー ビディングなどの非同期処理がサポートされます。次の例では、mediainfo オブジェクトの情報をもとにアカウント ID に応じて使用する広告 URL を決定しています。

// IMA プラグインを初期化
myPlayer.ima3({
  serverUrl: function(callback) {
    if (myPlayer.mediainfo.id === '4034552795001') {
      callback('https://pubads.g.doubleclick.net/.../url1');
    } else {
      callback('https://pubads.g.doubleclick.net/.../url2');
    }
  },
  requestMode: 'onload',
  debug: true
});

showVpaidControls

型: boolean
デフォルト値: false

true に設定すると、VPAID 広告の上に Brightcove のカスタム コントロールを表示します。VPAID の実装によっては動作しない場合があるため、本番環境で有効化する前に必ず広告でテストすることをお勧めします。

timeout

型: number
デフォルト値: 4000

広告ブレークがスキップされるまでに、広告の再生を待機する最大時間 (ミリ秒) です。

このオプションは広告フレームワークの一部であり、次のように構成します。

player.ima3({
  timeout: 5000
});

Brightcove の社内テストでは、4 秒は多くの場合で初期化の遅延に十分対応できる長さでありながら、初期化失敗がプレーヤーやコンテンツ動画の不具合のように見えないほど短い長さであることが分かりました。

useMediaCuePoints

型: boolean
デフォルト値: false

(Studio で定義される) ad キュー ポイントを使用して広告再生をトリガーすることを有効にします。

Video Cloud の広告キュー ポイントを広告のトリガーとして使用するには、プラグイン構成で次が必要です。

• useMediaCuePoints: true
• requestMode: 文字列 oncue
• serverUrl: 有効な VAST 広告を指している必要があります

Studio で広告を設定する場合、On cue point を選択すると、useMediaCuePoints と requestMode オプションが正しく設定されます。

vpaidMode

型: string
デフォルト値: ENABLED

IMA HTML5 SDK での VPAID 2 モードを指定します。

このオプションには 3 つの値を指定できます。

• ENABLED: 別ドメインの iframe で VPAID 広告を再生します。
• INSECURE: 同一ドメインの iframe で VPAID 広告を再生します。
• DISABLED: VPAID 広告はエラーをスローします。

このオプションは次のように構成します。

player.ima3({
  vpaidMode: 'DISABLED'
});

プロパティ

プラグインに存在するプロパティは 1 つだけです。

• html5: プラグイン初期化時に読み込める唯一の広告技術です。

広告マクロと serverUrl

広告サーバー URL を作成する際の作業を簡素化するために、広告マクロが用意されています。これらのマクロを使うと、サーバー URL に変数を含めることができ、IMA3 プラグインがその変数を適切な値に置換します。たとえば、次のサーバー URL にはいくつかの変数が含まれています。

{"serverUrl": "//myadserver.com/ad?video={mediainfo.id}&duration={player.duration}"}

IMA3 プラグインは適切な値で置換し、実際に使用されるサーバー URL は次のようになります。

{"serverUrl": "//myadserver.com/ad?video=12340001&duration=60"}

以下は、置換される値を持つ変数の完全な一覧です。

cust_params={mediainfo.ad_keys}

Brightcove Ad Monetization

SpringServe を使用する Brightcove Ad Monetization の広告タグには、最低限以下のマクロが含まれます。

プライバシー

広告タグにプライバシー関連のマクロを追加するには、ユーザーからデータを収集し、実行時にそれをプレーヤーに渡す実装が必要です。標準的な実装では、各変数はページ内またはアプリ内で同名のグローバル JavaScript 変数として定義されており、プレーヤーがそれにアクセスして広告サーバーに広告リクエストを送信する際に渡せるようにします。

ページやアプリ内で異なる名前で変数を定義している場合は、対応するマクロ名 (pageVariable.macro_name) も同名に更新してください。たとえば、ページの先頭にある <script> タグ内で次のように各変数を定義できます。

var my_gdpr_variable = true;

これにより、プレーヤーは {pageVariable.my_gdpr_variable} 経由で true という gdpr 値を取得できます。

デフォルト値と広告マクロ

広告マクロにはデフォルト値を指定できます。マクロ内でデフォルト値を指定でき、変数が未定義の場合にこの値が使用されます。構文は次のとおりです。

{macro=default}

たとえば、

http://example.com/ad/{pageVariable.adConf=1234}

は、window.adConf が未定義の場合、次のように解決されます。

http://example.com/ad/1234

動的マクロ

動的マクロを使用すると、次の値にアクセスできます。

• 動画の customFields オブジェクト (mediainfo.customFields 変数経由)。
• DOM の window オブジェクト (pageVariable 変数経由)。

たとえば、広告リクエストで次のように使用できます。

//myadserver.com/ad?l={pageVariable.navigator.language}&category={mediainfo.customFields.type}

pageVariable の値については、次の表に示す型のみ使用できます。

TCF マクロ

GDPR Transparency and Consent Framework (TCF) をサポートする同意管理プラットフォーム、すなわち CMP (各種広告技術を 1 つの使いやすいプラットフォームに統合したもの) が使用されている場合、追加のマクロが利用可能になります。構文は {tcf.*} で、* は tcData オブジェクトのプロパティです。

よく使用されるマクロは次のとおりです。

gdprApplies は boolean 値ですが、多くの広告サーバーが整数値を期待するため、追加で {tcf.gdprAppliesInt} も提供されており、1 または 0 を返します。

プレーヤーが iframe 内にある場合、いずれかの親フレームで TCF API が検出されると、postmessage API で同意を取得するためのプロキシが追加されます。CMP はプレーヤーより前に読み込む必要があります。

マクロのデフォルト値

マクロ内でデフォルト値を指定でき、解決できない場合にこの値が使用されます。たとえば、

http://example.com/ad/{pageVariable.adConf=1234}

http://example.com/ad/1234

になります。

カスタム広告マクロ

上述の Dynamic macros 手法は、マクロ経由で特定の情報にアクセスする推奨される方法ですが、動的マクロでは到達できないカスタム値を広告サーバーへの広告リクエスト時に使用したい場合があります。その場合、adMacroReplacement() メソッドをオーバーライドすることで自分の値を活用できます。このメソッドをオーバーライドすると、特殊な値を広告リクエストに渡せるようになります。

次は adMacroReplacement() メソッドのオーバーライド例です。この例では、ページの DOM の一部としてカスタム値を定義することで、ページごとに広告リクエストをカスタマイズできます。この例では、mySite.category が広告リクエスト情報の格納場所です。

brightcovePlayer.ima3.adMacroReplacement = function (url) {
    var parameters = {
    '{category}': mySite.category
  };
  for (var i in parameters) {
    url = url.split(i).join(encodeURIComponent(parameters[i]));
  }
  return url;
}

具体的な値を当てはめると分かりやすくなります。広告サーバーへのリクエスト URL が次のようになっているとします。

//myadserver.com/myads?adWord={category}

また、ページ内で mySite.category に動的に割り当てられている値が文字列 fishing-pole だとします。すると、自分のバージョンの adMacroReplacement() メソッドが呼ばれた後、広告リクエスト URL は次のようになります。

//myadserver.com/myads?adWord=fishing-pole

まとめると、adMacroReplacement() メソッドをオーバーライドすると、カスタム値を広告マクロとして使用したり、URL の広告リクエストに値を動的に割り当てたりできます。

メソッド

IMA SDK と対話する必要がある場合、SDK を正しく使用するには ima3-ready イベントがディスパッチされるのを待つ必要があります。これは以下の 2 つのメソッドにも該当します。

player.ima3.adrequest( )

このメソッドを呼び出すと、広告レスポンスを受け取った直後にオンデマンドの広告リクエストが作成されます。このメソッドを呼び出すと新しい IMA adManager が作成されるため、以前の広告レスポンス情報 (たとえば、以前の VAST レスポンスで返されたポストロール広告) は失われます。Brightcove は、広告タイミングが事前に分からない場合や、すべての広告呼び出しをオンデマンドで行う場合に限り、このメソッドを使用することを推奨します。それ以外の場合は、プラグイン初期化時の最初の VAST 呼び出しにすべての広告データを含めるのが理にかなっています。

player.ima3.adrequest( ) を使用する際の重要なポイントが 2 つあります。

• このメソッドは ondemand リクエスト モードでのみ使用してください。
• 広告リクエストの完了前にコンテンツが再生され始めるため、プリロールでの使用は推奨されません。

パラメーター

• adRequestUrl String VAST 広告タグへのパス。相対 URL を渡すこともでき、推奨されます。このパラメーターは任意で、渡されない場合は構成済みの serverUrl が使用されます。

戻り値:

• なし

例

player.ima3.adrequest('//pubads.g.doubleclick.net/gampad/ads?sz=640x360&iu=/6062/iab_vast_samples/skippable&ciu_szs=300x250,728x90&impl=s&gdfp_req=1&env=vp&output=xml_vast2&unviewed_position_start=1&url=[referrer_url]&correlator=[timestamp]');

player.ima3.setAdsRenderingSettings()

このメソッドでは、IMA SDK for HTML5 の広告レンダリング設定を行えます。

Ads Manager がまだ存在しない場合、このメソッドは設定を保存し、Ads Manager の作成時に渡された設定を使用します。Ads Manager がすでに存在する場合は、設定が更新されます。いずれの場合も、今後新たに作成される Ads Manager もすべて、最新の設定を使用します。AdsRenderingSettings オブジェクトは IMA SDK に直接アクセスして作成できます。さまざまな設定が利用可能です。

パラメーター

• google.ima.AdsRenderingSettings オブジェクト

戻り値:

• なし

例:

var adsRenderingSettings = new google.ima.AdsRenderingSettings();
adsRenderingSettings.bitrate = 2500;
adsRenderingSettings.enablePreloading = true;
player.ima3.setAdsRenderingSettings(adsRenderingSettings);

Google の AdsManager

Google の google.ima.AdsManager インターフェイスから利用可能なメソッドとプロパティがあります。情報を取得するインターフェイスのプロパティ / メソッドを使用できます。destroy、setAutoPlayAdBreaks、stop など、操作を実行するメソッドを使用することは推奨されません。たとえば、使用できるメソッドの一例を以下に示します。

AdsManager.getRemainingTime

型: google.ima.AdsManager.getRemainingTime

使用方法: myPlayer.ima3.adsManager.getRemainingTime()

このメソッドを呼び出すと、現在の広告の残り時間が返されます。広告が利用できないか、再生が終了している場合は -1 を返します。詳細は Google の ドキュメント を参照してください。

IMA SDK に直接アクセスする

実行時にプラグイン オブジェクト上で多くの IMA 設定を利用できます。たとえば、広告 ID を取得するには次のようにします。

var adId = player.ima3.currentAd.getAdId();

これらのプロパティを直接操作する際には注意してください。誤ったメソッドを呼ぶと予期しない結果になり、広告が正しく再生されない可能性があります。

adsLoader

型: google.ima.AdsLoader

広告リクエストを作成するために使用するオブジェクトです。ima.AdsLoader を参照してください。Ads Loader は、プラグインによって adsready がディスパッチされるまで利用できない場合があります。

adsManager

型: google.ima.AdsManager

広告再生を担当するオブジェクトです。ima.AdsManager を参照してください。Ads Manager は、プラグインによって adsready がディスパッチされるまで利用できません。

adDisplayContainer

型: google.ima.AdDisplayContainer

広告の表示要素を管理するオブジェクトです。ima.AdDisplayContainer を参照してください。Ads Display container は、プラグインによって adsready がディスパッチされるまで利用できない場合があります。

currentAd

型: google.ima.Ad

広告の再生中、現在の広告に関する情報をカプセル化したオブジェクトです。ima.Ad を参照してください。

イベント

このプラグインは、読み込み、初期化、再生中にいくつかのカスタム イベント タイプを発行します。IMA3 や広告フレームワークのイベントは、他のイベントと同じようにリッスンできます。

player.on('ima3-ready', function(event) {
  console.log('event', event);
});

再ディスパッチされる ima3- プレフィックス付きイベント

IMA3 プラグインを HTML モードで使用すると、すべての AdErrorEvents、AdEvents、AdsManagerLoadedEvents がプレーヤーに再ディスパッチされます。再ディスパッチされる際、これらには ima3- プレフィックスが付きます。再ディスパッチされるイベントは次のとおりです。

ライブ動画と IMA3

IMA3 プラグインのバージョン 3.1.0 以降を使用している場合、ライブ イベントでプリロールを使用できます。プリロールは、ライブ イベントが開始した一度きりではなく、各視聴者がライブ イベントを視聴し始めた時に再生されます。Live モジュールを使用したライブ イベントの作成および管理 ドキュメントの説明にあるように、Live モジュールでイベントを構成する際にプレーヤーを選択するよう求められます。ステップ・バイ・ステップ: 広告の実装 ドキュメントの説明に従って、選択したプレーヤーに対して広告を構成する必要があります。

実装の詳細は次のとおりです。

• プリロールのみが再生されます。ミッドロールおよびポストロールはサポートされません。
• Request Ads タイプは On load または On play のいずれかである必要があります。
• 前述のとおり、IMA3 プラグインの バージョン 3.1.0 以降 を使用している必要があります。

プレーヤー広告ライブラリ

videojs/videojs-contrib-ads GitHub リポジトリには、Brightcove Player と連携する動画広告ライブラリに必要な共通機能を提供するプラグインが含まれています。このプラグインは、動画広告の統合に必要な共通機能を提供し、広告統合担当者に代わって多くの懸念事項を処理するため、広告統合のために記述するコード量を削減できます。プラグインは詳細にドキュメント化されており、インデックス ページ から始めるのが最良です。

このプラグインからはメソッド、イベント、プロパティを利用できます。詳細は videojs-contrib-ads API リファレンス を参照してください。利用できるツールの一例を、まずメソッドから紹介します。

このプラグインは多数のイベントもディスパッチします。一部を以下に示します。

このプラグインは多数のプロパティも提供しています。一部を以下に示します。

以下のコードはこれらのプロパティの使用例です。

var myPlayer,
  player = bc('myPlayerID');
player.ima3({
  serverUrl: '//solutions.brightcove.com/bcls/brightcove-player/vmap/simple-vmap.xml'
});
player.ready(function () {
  myPlayer = this;
  myPlayer.on('ads-ad-started', function (evt) {
    console.log('ads-ad-started event passed to event handler', evt);
    console.log('myPlayer.ads.ad.id', myPlayer.ads.ad.id);
    console.log('myPlayer.ads.ad.index', myPlayer.ads.ad.index);
    console.log('myPlayer.ads.ad.duration', myPlayer.ads.ad.duration);
    console.log('myPlayer.ads.ad.type', myPlayer.ads.ad.type);
  });
});

上記コードによるコンソール出力は次のとおりです。

デバッグ支援

広告再生の問題をデバッグする際の支援には 2 つの選択肢があります。何もしない場合、コンソールには広告の開始と終了に関する情報のみが表示されます。

最初の選択肢は、本ドキュメントの前のほうの Options セクションで触れています。これによりプラグイン レベルでデバッグが有効になり、追加のデバッグ情報が表示されます。

2 つ目の選択肢は、Google が提供するツールを利用するものです。sdkurl オプションに、Google が提供する JavaScript ファイルを指す値を指定します。構成例は次のとおりです。

var myPlayer = bc('myPlayerID');
myPlayer.ima3({
  "serverUrl": "//solutions.brightcove.com/bcls/brightcove-player/vmap/simple-vmap.xml",
  "debug": true,
  "sdkurl": "//imasdk.googleapis.com/js/sdkloader/ima3_debug.js"
});
myPlayer.ready(function() {
  myPlayer = this;
});

拡張されたデバッグ情報は次のように表示されます (黄色のハイライトはプラグインのデバッグ情報、青色のハイライトは Google ツールが生成する情報です)。

Google の IMA エラーの詳細については、Google IMA HTML5 SDK APIs ドキュメントの Class google.ima.AdError セクションを参照してください。

既知の問題

ポストロール広告がある状態でプレイリストの動画を手動で進める場合

プレイリスト内の次の動画に手動で進めると、前の動画のポストロール (存在する場合) が新しい動画コンテンツの上に同時に再生されることがあります。あるいは、モバイル デバイスで手動でプレイリストを進めると、新しいコンテンツがまったく再生されない場合があります。

これは Google の IMA SDK ライブラリーの第三者起因の問題によるものです。この問題は今後の Google のリリースで対処される見込みです。

Safari の Stop Media With Sound 設定と autoplay: "play" または autoplay: true

Safari は自動再生に関して他のブラウザーと少し異なる挙動をします。具体的には、ブラウザー設定が Stop Media With Sound でミュートなしの自動再生を試みると、自動再生が拒否されたとしてもメディア要素は play および playing イベントを発火します。現状、これにより click-to-play へのスムーズなフォールバックができず、広告再生が失敗します。

この問題は今後の 4.x プラグイン リリースで対処されます。それまでの暫定策として、プレーヤーの autoplay 値には muted または any の使用をお勧めします。

オーバーレイ

オーバーレイ広告を使用していると、サムネイル シーク画像の位置がプログレス バーの左端に固定されたまま動かなくなる場合があり、プログレス バーをホバーしても拡大しないことがあります。

この問題は今後の 4.x プラグイン リリースで対処されます。

ライブ ストリームでのキュー ポイント広告

ライブ ストリームでキュー ポイントによる広告を再生すると、広告がミュートで再生され、ミュートを解除すると広告の背後にあるライブ ストリームのミュートも同時に解除されてしまいます。

この問題は今後の 4.x プラグイン リリースで対処されます。

Picture-in-Picture が無効

IMA3 プラグインが実装されている場合、picture-in-picture control は無効になります。これは意図的な設計上の判断です。

Studio で autoplay を設定する

IMA3 プラグインを使用して広告を表示する場合、Studio で autoplay を設定しないでください。Studio で autoplay を設定すると、広告再生に失敗することがあります。詳細は 自動再生に関する考慮事項 ドキュメントを参照してください。

Learn More および Ad Countdown Timer がデフォルトで表示されなくなった

Google の IMA SDK の useStyledLinearAds プロパティを使用した回避策があります。次のようにこの値を true に設定します。

adsRenderingSettings.useStyledLinearAds=true;

詳細は Google の google.ima.AdsRenderingSettings ドキュメントを参照してください。

Android の Chrome: プリロールのミュート解除で動画が自動再生されない

Android で最新版の Chrome を使用してプリロール再生中にプレーヤーのミュートを解除すると、プリロール終了後に動画が自動的に再生開始されません。広告のミュートを解除すると、Brightcove Player の音量永続化機能によりコンテンツのミュートも解除されます (これは視聴者が音声を聞きたいという意図と解釈されるためです)。しかし、新しいバージョンの Chrome Android では、ミュート解除されたコンテンツは自動再生できず、再生開始にユーザー ジェスチャーが必須となります。これは OS / デバイス レベルの設定であり、Brightcove では上書きできません。

プリロールの現在時間表示が正確でない場合がある

これは IMA SDK が現在時刻を報告する方法の制限によるものです。現時点で文書化された回避策はありません。

Safari 11 デスクトップでミュートなしのミッドロールが再生されない場合がある

Google の IMA SDK の変更により、Safari 11 デスクトップでミュートなしのミッドロールが再生されない場合があります。Safari 11 (デスクトップおよび iOS の可能性あり) で自動再生が拒否された場合に、エラーをトリガーして広告をキャンセルする新しい挙動が導入されました。これにより影響を受けるミッドロールは、自動再生が阻止されたことを示すエラー コード 1205 を伴う広告エラー 400 をトリガーします。

サポートされる環境

プラットフォーム、広告基準、動画メディアのサポートされる組み合わせを確認するには、Google の Video Feature and SDK compatibility ドキュメントを参照してください。このドキュメントと Video Suite Inspector は、機能しない IMA3 広告構成の試行を診断するのに役立ちます。

オーバーレイと全画面の遷移

video.js は、利用可能な場合は fullscreen API を使用します。ブラウザーごとに全画面への遷移実装が異なるため、全画面モードへの出入りで見た目に差異が生じることがあります。多くの実装では、全画面化される要素は元のサイズから目的のサイズへ幾何学的にスケール (拡大) されます。一方、ほとんどのオーバーレイ広告は固定サイズで表示するように設計されているため、アニメーションが完了するまでは歪んで見えることがあります。

iOS デバイス上のスキップ可能広告

IMA3 プラグインでは、次の条件を満たす場合に iPhone でスキップ可能広告を再生できます。

• video 要素に playsinline 属性が指定されていること
• プラグインに disableCustomPlaybackForIOS10Plus 設定を渡し、true に設定していること

playsinline 属性は、video タグに属性として含めるだけで使用できます。

<video-js id="player"
  width="640"
  height="360"
  data-video-id="4524585416001"
  data-account="4360108595001"
  data-player="r12ukws9l"
  data-embed="default"
  playsinline
  controls></video-js>

disableCustomPlaybackForIOS10Plus 設定は、ima3SdkSettings のプロパティとして割り当てます。

player.ima3({
  ima3SdkSettings: {
    "disableCustomPlaybackForIOS10Plus": true
  }
})

Studio で設定を使用したい場合は、IMA3 プラグイン構成に次を追加します。

{
  "ima3SdkSettings": {
    "disableCustomPlaybackForIOS10Plus": true
  }
}

この設定の詳細については、本ドキュメントの ima3SdkSettings セクション内の disableCustomPlaybackForIOS10Plus エントリーを参照してください。

スキップ可能広告の制限事項:

• 一部のモバイル デバイスでは、Skip Ad ボタンが 広告コントロール バーで部分的に隠される 場合があります。これにより、エンド ユーザーが広告を実際にスキップするのが難しくなります。ユーザーはモバイル デバイスでピンチ ズームすることで Skip Ad ボタンを大きくしてクリックできます。
• iPhone で playsinline および disableCustomPlaybackForIOS10Plus がない場合 - スキップ可能広告は再生されません。
• iPhone で playsinline および disableCustomPlaybackForIOS10Plus がある場合 - 広告はインラインで再生されますが、全画面表示を使用すると広告は表示されず、広告の音声のみが再生されます。つまり、全画面でのスキップ可能広告は正しく機能しません。
• iPad - 広告はインラインで再生されますが、全画面モードではスキップが利用できません。

iOS 10 iPad および iPhone: playsinline 使用時に全画面化するとプリロール広告が動作しない

iOS 10 iPad および iPhone で playsinline を使用して動画を全画面ではなく表示し、その状態でプリロール広告が開始してから全画面ボタンをクリックすると、広告は再生を継続しません。これは Google の IMA 実装の制限であり、Google は問題を修正する予定がありません。

gpt_proxy.js との競合

IMA3 で GPT プロキシ スクリプトを使用し、adTechOrder が HTML5 を最初にしている場合、再生の問題が発生する可能性があります。IMA3 プラグインは、window.google または window.google.ima を使用するスクリプトの影響を受けます。Brightcove Player を使用しているかチェックし、使用している場合はプロキシを読み込まないようにすることを推奨します。

Skip Ad ボタンのリサイズ

Skip Ad ボタンをリサイズすることはできません。Brightcove Player API には、Skip Ad ボタンのサイズを指定するためのメソッドやプロパティはありません。開発者レベルでは、パブリッシャーが VPAID 広告を使用している場合、広告が独自の Skip Ad ボタンとロジックを実装し、Brightcove Player の UI と要素配置に収まるようにできます。

iOS では広告は自動再生されない

これは IMA3 プラグインに固有の問題ではありませんが、iOS では autoplay が制限されているため、ユーザー ジェスチャーが行われるまで広告は開始しません。

広告キュー ポイントの問題

広告キュー ポイントの使用に固有の問題については、Displaying Ads Using Ad Cue Points ドキュメントの Known issues セクションを参照してください。

IMA3 SDK の url パラメーター

Google Ad Manager の url パラメーターは、広告リクエストの送信元の完全な URL です。この値は IMA SDK によって自動的に設定され、指定した値は実際には上書きされる点に注意してください。