外部広告要求を使用する

標準の Brightcove 広告フォーマットは通常、Brightcove プレーヤのレイアウト内に表示されます。しかし Brightcove の外部広告 API を使用すれば、プレーヤの外側、つまり Web ページの任意の場所に広告を表示できます。外部広告を使用して、埋め込まれたシングル動画プレーヤから、大型のマルチプレイリスト プレーヤまで、他の広告ユニットを任意の Brightcove プレーヤと同期させることができます。外部広告の配置は、Brightcove プレーヤとのやり取りを記述した JavaScript か ActionScript で行います。このコードは、ページ（JavaScript）またはSWF（ActionScript）としてサイト上に配備し、管理します。一体化したデザインとこれらの API により、シームレスなユーザー エクスペリエンスを実現できます。

お使いのプレーヤ テンプレートで、プレーヤ内の広告ユニットの同期がサポートされている場合は、通常どおりにこれらをトラフィックするか、または他のデザイン要素のためにプレーヤ内のスペースを利用することができます。

デフォルトでは、広告応答が広告サーバーからプレーヤに返されると、プレーヤはその応答が既知のサポート対象の広告フォーマットに合致する XML 形式かどうか検証します。合致していたら、プレーヤは通常どおり広告を表示します。合致せず、外部広告が有効になっていない場合は、その広告応答は無視されます。しかし外部広告が有効にしてあれば、広告応答を外部広告関数へ送り、広告の処理と表示をさせることができます。

つまり、外部広告を表示したい場合には、受信する広告がサポート対象の広告フォーマットと一致しないようにする必要があります。広告応答の XML で、異なるルート要素を使用すれば簡単です。たとえば、外部広告が 468x60 バナーの場合、ルート ノードを <Banner468x60> と区別するために <BannerExternal468x60> とします。そして、広告が <BannerExternal468x60> で返されれば、それはサポート対象の広告フォーマットとは認識されず、外部広告関数によって処理されます。

外部広告関数は、受信した外部広告の処理を完全に制御できます。外部広告関数では、受信した XML をパースし、指定された広告ユニットを認識し、プレーヤの外側または内側の適切な位置に表示する必要があります。

JavaScript または ActionScript を使用して外部広告を実装する方法を示すサンプルをまとめた zip ファイルをダウンロードできます。

このトピックでは次の項目について説明します。

• 外部広告要求:手順の概要
• 外部広告要求を作成する:JavaScript
• 外部広告要求を作成する:ActionScript
• 広告特有のイベント
• プレーヤの広告動作をオーバーライドする
• サポート対象の広告フォーマット

外部広告要求:手順の概要

次の手順では、外部広告のセットアップ方法の概要を説明します。詳細な説明は、それぞれ JavaScript か ActionScript のセクションを参照してください。

1. 外部広告を有効にしたことを示すパラメータをコードに追加します。
2. プレーヤをこのように構成すると、広告サーバーから返された XML に未知の広告フォーマットが含まれていない限り、通常どおり広告を再生します。未知のフォーマットが含まれていた場合は、プレーヤは動画再生を中止し、関数を呼び出すか（JavaScript）、イベントを発生させます（ActionScript）。
3. 外部広告サーバーの呼び出しをしたり、または単純に追加の広告フォーマットを表示するなど、任意の方法で外部広告を処理するコードまたはハンドラを実行します。

また、enableOverrideAds プロパティを true に設定することで、プレーヤが広告要求を行わないようにすることができます。この場合、プレーヤは自らの広告ロジックに基づいて広告の要求を行うタイミングを判断し続けますが、外部サーバーを呼び出さずに再生を中止します。広告フォーマットを外部コードに渡す代わりに、プレーヤ コンテキスト（title や lineupId など）を渡し、それに従ってコードにより広告を提供できるようにします。詳細については、プレーヤの広告動作をオーバーライドするを参照してください。

Brightcove プレーヤではなくカスタム Flash Player を使用している場合、allowScriptAccess を true に設定する必要があることに注意してください。

外部広告要求を作成する:JavaScript

重要:プレーヤに JavaScript を使用している場合、Publishing モジュールでプレーヤの [Enable ActionScript/JavaScript APIs] を確認するだけでなく、プレーヤの公開コードに以下の行を追加する必要があります。

<script src="http://admin.brightcove.co.jp/js/APIModules_all.js"> </script> 

プレーヤを埋め込んだページで JavaScript を使用して外部広告を有効にするには、プレーヤ API の Ad Module の enableExternalAds メソッドを呼び出して外部広告パラメータを true に設定し、External Ad イベントのコールバック関数を設定します。ExperienceEvent.TEMPLATE_LOADED のイベント ハンドラでこのメソッドを呼び出すことをお勧めます。通常、下記の例のように、このハンドラは onTemplateLoaded(event) と設定されます。プレーヤは未知のフォーマットを受け取ると、動画再生を中止し、受け取った広告 XML を渡すコールバック関数を呼び出します。プレーヤ API の広告モジュールの resumeAfterExternalAd() メソッドを呼び出し、プレーヤに制御を戻してください。次に例を示します。

<script language="javascript">
  var player;
  var adModule;
 
  // テンプレートがロードされると呼び出される。プレーヤおよびモジュールへの参照を保管し、
  // 外部広告のイベント リスナを追加するのに使用する
  function onTemplateLoaded(experienceID) {
    player= brightcove.getExperience(experienceID);
    // 広告モジュール API への参照を取得
    adModule = player.getModule(APIModules.ADVERTISING);
    //外部広告を有効化
    adModule.enableExternalAds(true);
    // externalAd イベントのコールバック関数を設定 
    adModule.addEventListener(BCAdvertisingEvent.EXTERNAL_AD, onExternalAd);
    // Ad Complete イベントのコールバック関数を設定
    adModule.addEventListener(BCAdvertisingEvent.AD_COMPLETE, onAdComplete); 
  }
  
  function onExternalAd(evt) {
    /* adXML で必要な広告アクションを実行する（例 adModule.showAd(adXML) ）。
      完了した後、resumeAfterExternalAd を呼び出し、
      プレーヤに制御を戻すことができる。この例では、resumeAfterExternalAd は onAdComplete と呼ばれている */ 
  }
 
  function onAdComplete(evt) {
    adModule.resumeAfterExternalAd(); 
  }
  
  </script>
 

JavaScript を使用した外部広告の実装例については、Ad API サンプルの zip ファイルをダウンロードしてください。JavaScript のサンプルは、external-ads-examples/enableExtAds ディレクトリにあります。

外部広告要求を作成する:ActionScript

JavaScript と同様に、ActionScript では以下のようにして外部広告を有効にします。

1. 広告モジュール API の enableExternalAds メソッドを呼び出し、
2. externalAd イベントにコールバック関数を設定し、
3. resumeAfterExternalAd() メソッドを呼び出すことにより、プレーヤに制御を戻します。

プレーヤは広告を通常どおり再生しますが、広告から返された XML が未知の広告フォーマットだった場合、プレーヤは動画再生を中止して externalAd イベントを発生させます。プレーヤ API の広告モジュールの resumeAfterExternalAd() メソッドを呼び出し、プレーヤに制御を戻してください。次に例を示します。

package {
// Brightcove プレーヤをインポート
import BrightcovePlayer;	
import flash.display.Sprite;
import flash.events.Event;
 
public class SingleVideoPlayerExternalAds extends Sprite {
  
  private var bcp:BrightcovePlayer = new BrightcovePlayer();
  private var adModule:Object;

  public function SingleVideoPlayerExternalAds() {
    addChild(bcp);
    bcp.addEventListener("templateLoaded", templateLoaded);
  }
		
  // プレーヤがロードされていれば呼び出す
  public function templateLoaded(evt:Event):void {
    // 広告モジュール APIへの参照を取得
    adModule = bcp.getModule("advertising");
    // 外部広告を有効化
    adModule.enableExternalAds(true);
    // externalAd イベントのコールバック関数を設定
    adModule.addEventListener("externalAd", onExternalAd);
  }
 
  public function onExternalAd(evt:Event):void {
    /* adXML で必要な広告アクションを実行する（例 adModule.showAd(adXML) ）。
       完了した後、resumeAfterExternalAd を呼び出し、プレーヤに制御を戻すことができる */
    var adXML:XML = new XML (evt["ad"]);
    trace(adXML);  
    adModule.resumeAfterExternalAd();
  }	
}

ActionScript を使用した外部広告の実装例については、Ad API サンプルの zip ファイルをダウンロードしてください。ActionScript のサンプルは、external-ads-examples/extAdsAS3 ディレクトリにあります。

広告特有のイベント

プレーヤでは、広告処理に特有の、サブスクライブ可能なイベントを発生させます。これらのイベントは、JavaScript と ActionScript で共通です。

イベント	説明
externalAd	広告挿入ポイントに達したときに、(a) 開発者が広告のオーバーライド フラグを true にすることにより、プレーヤにおけるすべての広告要求をオーバーライドするよう設定していた場合、もしくは (b) 広告サーバーから未知の広告フォーマットが返され、開発者が外部広告フラグ true に設定していた場合に発生します。
adStart	動画ウィンドウにおける、広告の最初の再生が開始したときに発生します。
adResume	動画ウィンドウにおける、広告の再生が一時停止後に再開したときに発生します。
adPause	動画ウィンドウにおける、広告の再生が一時停止したときに発生します。
adProgress	動画ウィンドウにおける、広告の再生中に発生します。視聴者に対して進行状態やカウントダウンを表示するために、このイベントを使用できます。
adComplete	プレーヤにおいて、広告の再生が終了したときに発生します。

JavaScript では、イベント名をハードコードする代わりに、イベント定数を使用できます。

BCAdvertisingEvent.AD_COMPLETE = "adComplete";
BCAdvertisingEvent.AD_PAUSE = "adPause";
BCAdvertisingEvent.AD_PROGRESS = "adProgress";
BCAdvertisingEvent.AD_RESUME = "adResume";
BCAdvertisingEvent.AD_START = "adStart";
BCAdvertisingEvent.EXTERNAL_AD = "externalAd";

プレーヤの広告動作をオーバーライドする

上記の機能に加えて、プレーヤの広告要求をオーバーライドすることもできます。JavaScript と ActionScript のいずれも、enabledOverrideAds メソッドでこの機能を有効にできます。enabledOverrideAds が呼び出されると、プレーヤは自らの広告ロジックに基づいて、広告が必要とされる場所や数について評価を続けます。ただし、広告を表示する必要があると判定したときには、外部広告サーバーへの呼び出しは行わず、再生を中止して以下の処理を行います。

JavaScript の enabledOverrideAds

externalAd イベントが発生します。ただし、この関数はサーバーから受信した広告情報を送信する代わりに、以下の形式の XML オブジェクトを受け取ります。

<externalAd lineupId="0" titleId="17038"/>

そして JavaScript コードはプレーヤのコンテキストの外で実行されます。プレーヤに制御を戻すために、プレーヤ API の広告モジュールの resumeAfterExternalAd() メソッドを呼び出します。広告をオーバーライドする設定により、外部広告を再生する例については、Ad API サンプルの zip ファイルをダウンロードしてください。JavaScript のサンプルは、external-ads-examples/extAdsOverrideAds ディレクトリにあります。

ActionScript の enabledOverrideAds

上記の最初の ActionScript の例と同様に、externalAd イベントが発生します。ただしイベント オブジェクト内の広告情報を送信する代わりに、このハンドラは以下の形式の広告 XML を受け取ります。

<externalAd lineupId="0" titleId="17038"/>

ActionScript とその shell.SWF はプレーヤのコンテキストの外で必要なことを行い、それからプレーヤ API の広告モジュールの resumeAfterExternalAd() メソッドを呼び出して、プレーヤに制御を戻します。プレーヤが所定の XML 形式に組み立てたプロパティのコレクションを渡すことにより、ActionScript API を使用してプレーヤ内で Flash Video を再生できます。

adModule.showAd(adObject:Object);

プレーヤは、動画広告が完了すると、広告が完了した後で通常実行する処理を行います（広告の前に再生をしていた場合は再開し、広告ロジックで別の広告を必要としている場合は再び externalAd イベントを発生させます）。

サポート対象の広告フォーマット

このセクションでは、プレーヤの showAd() メソッドでサポートされている広告クリエイティブのフォーマットの一覧を示します。どのプレーヤテンプレートでも、すべてのフォーマットが利用できるわけではありません。

• バナー
• 動画広告
• 同期バナー
• オーバーレイ

trackStartURLs プロパティ

各広告フォーマットには trackStartURLs プロパティがあります。このプロパティで、インプレッションを追跡するためにアクセスする URL のリストを設定できます。この属性は、単なる文字列ではなく配列として送信する必要があります。そうしないと、トラッキング ポイントが発生しません。次に例を示します。

objAd.trackStartURLs = ["http://tracking.com"];

または、複数の追跡 URL では

objAd.trackStartURLs = ["http://tracking.com","http://tracking2.com" ];

であり、次の値ではありません。

objAd.trackStartURLs = "http://tracking.com";

バナー

プロパティ	説明
type:String	広告フォーマット（「banner」）
trackStartURLs:Array	バナー表示時に、インプレッションを追跡するためにアクセスする URL のリスト
bannerURL:String	バナー アセットの URL（JPG または SWF）
bannerClickURL:String	バナーがクリックされたときに開く URL

バナーの例

var ad =
    {
    type:"banner",
    bannerURL:"http://www.site.com/ad.jpg",
    bannerClickURL:"http://www.site.com",
    trackStartURLs:["http://someTrackingServer"]
    }; 
adModule.showAd(ad);

動画広告

プロパティ	説明
type:String	広告フォーマット (「videoAd」)
trackStartURLs:Array	動画の再生開始時に、インプレッションを追跡するためにアクセスする URL のリスト
videoURL:String	動画アセットの URL（FLV または SWF）
videoClickURL:String	動画がクリックされたときに開く URL
duration:Number	動画の長さ（秒）

動画広告の例

var ad =
    {
    type:"videoAd",
    videoURL:"http://www.site.com/ad.flv",
    videoClickURL:"http://www.site.com",
    trackStartURLs:["http://someTrackingServer"],
    duration:10
    }; 
adModule.showAd(ad);

同期バナー

プロパティ	説明
type:String	広告フォーマット（「synchedBanner」）
trackStartURLs:Array	動画の再生開始時に、インプレッションを追跡するためにアクセスする URL のリスト
videoURL:String	動画アセットの URL（FLV または SWF）
videoClickURL:String	動画がクリックされたときに開く URL
collapsedBannerURL:String	スモール バナー アセットの URL（JPG または SWF）
expandedBannerURL:String	ラージ バナー アセットの URL（JPG または SWF）
bannerClickURL:String	いずれかのバナーがクリックされたときに開く URL
duration:Number	動画の長さ（秒）

同期バナーの例

var ad =
    {
    type:"synchedBanner728x90",
    videoURL:"http://www.site.com/ad.flv",
    videoClickURL:"http://www.site.com",
    bannerClickURL:"http://www.site.com",
    collapsedBannerURL:"http://www.site.com/collapsedAd.jpg",
    expandedBannerURL:"http://www.site.com/expandedAd.jpg",
    trackStartURLs:["http://someTrackingServer"],
    duration:10
    }; 
adModule.showAd(ad);

オーバーレイ

プロパティ	説明
type:String	広告フォーマット (「overlay」)
trackStartURLs:Array	オーバーレイの再生開始時に、インプレッションを追跡するためにアクセスする URL のリスト
overlayURL:String	オーバーレイ アセットの URL（SWF）
overlayClickURL:String	オーバーレイがクリックされたときに開く URL
duration:Number	オーバーレイ広告の長さ（秒）

オーバーレイの例

var ad =
    {
    type:"overlay",
    overlayURL:"http://www.site.com/ad.swf",
    overlayClickURL:"http://www.site.com",
    trackStartURLs:["http://someTrackingServer"],
    duration:10
    }; 
adModule.showAd(ad);

コンパニオン付きオーバーレイ

プロパティ	説明
type:String	広告フォーマット（「SynchedOverlay468x60」）
trackStartURLs:Array	動画の再生開始時に、インプレッションを追跡するためにアクセスする URL のリスト
overlayURL:String	オーバーレイ アセットの URL（SWF）
overlayClickURL:String	オーバーレイがクリックされたときに開く URL
collapsedBannerURL:String	スモール バナー アセットの URL（JPG または SWF）
expandedBannerURL:String	ラージ バナー アセットの URL（JPG または SWF）
bannerClickURL:String	いずれかのバナーがクリックされたときに開く URL
duration:Number	動画の長さ（秒）

コンパニオン付きオーバーレイの例

var ad =
    {
    type:"SynchedOverlay468x60",
    overlayURL:"http://www.site.com/ad.swf",
    overlayClickURL:"http://www.site.com",
    bannerClickURL:"http://www.site.com",
    collapsedBannerURL:"http://www.site.com/collapsedAd.jpg",
    expandedBannerURL:"http://www.site.com/expandedAd.jpg",
    trackStartURLs:["http://someTrackingServer"],
    duration:10
    }; 
adModule.showAd(ad);