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

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

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

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

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

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

<script language="javascript">
  var player;
  var adModule;

  // テンプレートがロードされるときに呼び出されます。これを使用して、プレーヤとモジュールへの
  // リファレンスを格納し、外部広告用のイベントリスナーを追加します。
  function onTemplateLoaded(experienceID) {
    player= brightcove.getExperience(experienceID);
    // Ad Module API へのリファレンスを取得します。
    adModule = player.getModule(APIModules.ADVERTISING);
    // External Ads を有効にします。
    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 ディレクトリにあります。

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

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

プレーヤは広告を通常どおり再生しますが、広告から返された XML が未知の広告フォーマットだった場合、プレーヤは動画再生を中止して externalAd イベントを発生させます。Player API の Ad Module の 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 mAdModule:Object;
  public function SingleVideoPlayerExternalAds()
    {
    addChild(bcp);
    bcp.addEventListener("templateLoaded", templateLoaded);
    }
		
  // プレーヤがロードされたときに呼び出します。
  public function templateLoaded(evt:Event):void {
    // Ad Module API へのリファレンスを取得します。
    mAdModule = bcp.getModule("advertising");
    // External Ads を有効にします。
    mAdModule.enableExternalAds(true);
    // externalAd イベント用のコールバック関数を設定します。
    mAdModule.addEventListener("externalAd", onExternalAd);
	
    }

public function onExternalAd(evt:Event):void {		
			
/* 必要な広告アクションをすべて adXML(つまり adModule.showAd(adXML) ) で実行します。
   終了したら、resumeAfterExternalAd を呼び出して、制御をプレーヤに戻すことができます。 */
  var adXML :  XML = new XML (evt["ad"]);
  
  trace(adXML);
  
  mAdModule.resumeAfterExternalAd();
  }	
}

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

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

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

ActionScript の enabledOverrideAds

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

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

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

adModule.showAd(adObject:Object); 

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

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

バナー

動画広告

同期バナー

オーバーレイ

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

バナー

バナーの例

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

動画広告

動画広告の例

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

同期バナー

同期バナーの例

var ad:Object =
    {
    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);

オーバーレイ

オーバーレイの例

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

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