Ad Translator を開発する

このトピックでは、Ad Translator の作成方法を説明します。Ad Translator により、Video Cloud プレーヤと広告サーバーを容易に統合できます。デフォルトでは、Video Cloud プレーヤは DoubleClick DART for Publishers と統合するよう設定されています。

Ad Translator が利用できるのは、Video Cloud Pro エディションと Enterprise エディションをご購入の方のみです。Video Cloud アカウントのアップグレードについては、ブライトコーブにお問い合わせください。

このトピックでは、Ad Translator の作成方法を説明します。Ad Translator により、Video Cloud プレーヤと広告サーバーを容易に統合できます。デフォルトでは、Video Cloud プレーヤは DoubleClick DART for Publishers と統合するよう設定されています。さらに、Advertising モジュールを使用して、他の広告サーバーに対して複数の広告トランスレータと統合するようプレーヤを設定できます。Ad Translator を使用して、Video Cloud プレーヤをほぼすべての広告サーバーに統合できます。その基本的な仕組みを説明します。

Ad Translator は、Video Cloud プレーヤにより実行時にロードされる Flash SWF ファイルであり、プレーヤと広告サーバー間の広告要求のプロキシとして機能します。
Ad Translator はプレーヤごとに使うことも、アカウントレベルですべてのプレーヤに使うことも可能です。バイラルに配布されたプレーヤやシンジケートされたプレーヤでも使用できます。

以前は、Video Cloud プレーヤと DFP 以外の広告サーバー間の統合には、Video Cloud API を使用したカスタム開発が必要でした。Video Cloud がサポートしている広告フォーマットを使用する限り、Ad Translator SWF を作成すると、DFP 以外の広告統合に対応するために API を使用する必要はありません。ただし、独自の広告フォーマットを再生する場合や、プレーヤの外側で広告を再生する場合、あるいはプレーヤ内で動画用に Ad Translator を動的に切り替える場合は、Video Cloud が必要です。

Video Cloud は、主要な広告サーバーに対して、一連の Ad Translator を開発中です。今回のリリース時点で利用可能な Ad Translator の一覧は、広告統合を参照してください。Ad Translator の独自の開発を始める前に、使用できるものがあるかどうか、担当者もしくはカスタマサポートにお問い合わせください。

Ad Translator:手順の概要

ご利用のアカウントで、Ad Translator を使用した統合を実施するには、以下の手順を行います。

「Ad Translator SWF を作成する」の説明に従い、Ad Translator クラスを作成して、SWF にコンパイルします。
お持ちのドメインで Ad Translator SWF をホストします。
開発した Translator をテストするために、Video Cloud Advertising モジュールにおいて、プレーヤレベルで Ad Translator のパスを設定することができます。詳細は、「Ad Translator を設定する」を参照してください。
テストを終了し、その Ad Translator をアカウントの全プレーヤでのデフォルト設定にしたい場合に、パブリッシャアカウント用にトランスレーション SWF パスを設定するには、ブライトコーブのサポートにお問い合わせください。

Ad Translator を使用する

Ad Translator を使用するためには、お使いの広告サーバーでは広告要求に何が必要とされるか、そして広告要求に対する応答で何が返されるかを理解する必要があります。こうしたことは Video Cloud の一切の実装から切り離されており、広告サーバーごと、場合によっては広告サーバーの設定ごとに異なります。Video Cloud が提供する Ad Translator のフレームワークでは、標準の ActionScript を使用して、プレーヤが広告要求を行ったときに SWF へ通知することができます。また、広告要求時のプレーヤのコンテキストを提供します。広告サーバーとのすべての通信、そして応答の解析は、Ad Translator を介してクライアントで処理されます。

Ad Translator SWF は、2 つの基本タスクを実行する必要があります。

広告サーバーに対する広告要求を行う
XML の広告応答を広告サーバーから受け取り、そこから広告を作成する

Flash Player が他のドメインのファイルと連動することは、Flash のセキュリティ機能によって制限されています。Ad Translator をホストしているドメインへプレーヤからアクセスできるようにするには、サイトの crossdomain.xml ファイルを編集する必要があります。これについては「Ad Translatorのためのクロスドメインセキュリティ設定」を参照してください。

Ad Translator SWF を作成する

Ad Translator 開発は、サンプルファイル Example.as を使用して始めることができます。Ad Translator の外部ライブラリである Example.as と bc_ads.swc を zip ファイルでダウンロードできます。さらに、zip ファイルには AdContext、AdTranslation、TranslationURLLoader クラスの API リファレンスが含まれています。

Flash Authoring で Ad Translator を作成する

Adobe Flash CS3 を使用して、ActionScript の .fla ファイルを新しく作成します。
作成した .fla ファイルと、サンプルの zip ファイル AdSDK.zip から解凍した Example.as と bc_ads.swc を配置するフォルダを作成します。
Flash IDE の [Properties] パネルか、または [File] > [Publish Settings] > [Flash] タブ > [Actionscript 3.0 Settings] で、Example.as を Document クラスに設定します。
Example.as ファイルを編集し、必要に応じて fetchAd 関数と onAdLoad 関数をお使いの広告サーバーに合わせて変更します。
作成したトランスレータの .fla ファイルと同じディレクトリに bc_ads.swc があることを確認して、.fla をパブリッシュします（CTRL + Enter）。外部ライブラリの bc_ads.swc を使用することで、SWF ファイルのサイズに影響を与える多くのファイルをインクルードすることなく、トランスレータをコンパイルできます。
.fla のコンパイルが成功し、作成した .fla ファイルと同じディレクトリに SWF ファイルが出力されます。
Ad Translator SWF をプレーヤからアクセス可能な Web サーバー上でホストします。
Ad Translator の URL を設定します。Advertising モジュールで、プレーヤを 1 つ選択し、Ad Translator を Custom に設定して、Ad Translator の URL を入力します。getAdTranslator および setAdTranslator メソッドを使用して、Ad Translator URL を動的に割り当てることができます。これらのメソッドは、プレーヤ内における動画の Ad Translator のオンザフライスイッチングに使用することができます。広告ソースの動的切り替えにこれらのメソッドを使用する方法については、「Player API の Advertising モジュールクラス」で例をご覧ください。

プレーヤから広告を要求すると、Henderson の動画広告が表示されます。

Flex Builder で Ad Translator を作成する

新しい ActionScript プロジェクトを作成します。1 番目の画面で、[Project contents folder] をサンプルのソースファイルがある場所に変更します。[次へ] をクリックします。
2 番目の画面で、[Main source folder] を空文字列に変更します。
[Library path] タブをクリックし、[Add SWC] をクリックして bc_ads.swc を追加します。
[Main application file] を Example.as に変更して、[Finish] をクリックします。
このプロジェクトを右クリックし、[Properties] を選択します。[ActionScript Properties] をクリックし、[Additional Compiler Options] に「"-load-externs bc_ads_extern.xml"」を追加します。
Example.as ファイルを編集し、必要に応じて fetchAd 関数と onAdLoad 関数をお使いの広告サーバーに合わせて変更します。
プロジェクトをビルドすると、bin-debug フォルダに Example.swf という名前のファイルができます。
Ad Translator SWF をプレーヤからアクセス可能な Web サーバー上でホストします。
プレーヤ向けに Ad Translator の URL を設定します。Advertising モジュールで、プレーヤを 1 つ選択し、Ad Translator を Custom に設定して、Ad Translator の URL を入力します。

プレーヤから広告を要求すると、Henderson の動画広告が表示されます。

注：bc_ads.swc と BrightcovePlayerAPI.swc の両方を Ad Translator SWF で使用するには、プロジェクトのセットアップでいくつか変更する必要があります。Adobe Flex Builder を使用している場合、bc_ads.swc と BrightcovePlayerAPI.swc の両方を通常のライブラリとして追加します。これはプロジェクトのプロパティ（Library path タブ）で行うか、Additional Compiler Options に -library-path=../bc_ads.swc を追加します。また、AdContext.moduleLoader を、開発 SWC の両方で使用する場合（例えば moduleLoader = new BrightcoveModuleWrapper（context.moduleLoader as IEventDispatcher））、com.brightcove.fl.advertising.api.BrightcoveModuleWrapper にラップする必要があります。両方の開発 SWC を追加して moduleLoader をラップすると、すべての変数をタイプし SWC を完全に使用することができます。

Ad Translator クラスファイル

Example.as について、Ad Translator の基本構造をどのように実装しているか見てみましょう。

広告タグトランスレーションクラスは ActionScript 3.0 Flash クラスの一種であり、com.brightcove.fl.advertising.translation.AdTranslation を継承します。
広告タグトランスレーションクラスは、外部ライブラリとして追加する必要がある bc_ads.swc に依存しています。
クラスコンストラクタで、プレーヤに対するイベントフックを追加したり、広告トランスレーションに必要なものをロードすることができます。
もっとも重要な関数は、広告要求を行う fetchAd() と、応答をパースし、それに基づいて広告の表示を行う onAdLoad() です。

広告要求を行う

作成する Ad Translator クラスでは、fetchAd() 関数をオーバーライドする必要があります。これは、広告要求を行うための主要な関数です。fetchAd() 内では、com.brightcove.fl.advertising.translation.TranslationURLLoader を使用して URL を構築し、それを広告サーバーに送信します。この関数は同じ形式で組み込む必要がありますが、中身は広告サーバーの実装によって変わります。広告が要求されると、プレーヤはこの関数を呼び出して AdContext のインスタンスを渡します。AdContext オブジェクトは、プレーヤの広告要求時点での状態を示すプロパティのコレクションです。動画、キューポイント、キーと値のペアなどのプロパティが含まれています。AdContext オブジェクトで設定できるプロパティの一覧については、「Ad API リファレンス」の AdContext object を参照してください。

サンプルの fetchAd() 関数は、以下のようになっています。

override public function fetchAd(context:AdContext):void {
  // 広告関連のパラメータで URL を作成
  var url:String = createAdRequestURL(context);
  trace("Created the ad url: " + url);
      
  // 広告を要求し、onAdLoad 関数に応答を送信する 
  //loader.load(url, onAdLoad, onAdLoadError);
 
  // 通常は、すぐ上に示したように、この時点で loader.load() を呼び出す。 
  // ただし、これはサンプルであり、呼び出すべき実際の広告サーバーはないので、
  // 自分の広告をローカルに作成し、onAdLoad() を直接呼び出す
    var fakedResponse:String = "<videoAd version='1' duration='15' houseAd='true'>" + 
        "<videoURL>http://brightcove.vo.llnwd.net/o2/unsecured/ads/Hendersons_15fps.flv</videoURL>" + 
    "</videoAd>"; // サンプル用の行
  onAdLoad(fakedResponse); // サンプル用の行
}

この fetchAd() 関数では、createAdRequestURL() 関数を使用して広告要求を組み立てていますが、fetchAd() 関数内で広告要求を組み立てることもできます。サンプルの createAdRequestURL() 関数は、以下のようになっています。

private function createAdRequestURL(context:AdContext):String {
  // 最初に広告サーバーの URL を取得 
  var adServerURL:String = context.adServerURL;
  // カスタムのキー/値をすべて結合
  var userKeyValues:String = "";
  if (context.playerKeyValues) userKeyValues += DELIM + context.playerKeyValues;
  if (context.titleKeyValues) userKeyValues += DELIM + context.titleKeyValues;
  if (context.insertionKeyValues) userKeyValues += DELIM + context.insertionKeyValues;
  if (userKeyValues.length > 1) userKeyValues += DELIM;
  // 広告サーバーのデリミタを ";" セパレータに変換する必要があります。 
  // 例の場合、架空の広告サーバーのデリミタは「;」なので、
  // ここでは次の行は必要ありません 
  userKeyValues = userKeyValues.replace(/;/g, DELIM); 
  // 広告サーバーに現在のフォーマットについて通知
  var adFormats:String = "";
  for(var i:Number = 0; i < context.adFormats.length; i++) {
   adFormats += "frmt=" + context.adFormats[i] + DELIM;
  }

  // キュー タイプ:  onLoad、Pre-roll、Mid-roll、または Post-roll
  var cue:String = context.type;
  if (cue == AdContext.CUE) {
   cue = context.cuePoint.name;
  }
  cue += DELIM;
 
  // プレーヤ ID
  var playerID:String = "plID=" + context.playerID + DELIM;
  // 呼び出しの終了時のタイムスタンプ
  var timestamp:Number = (new Date()).getTime();
  var ord:String = "ord=" + timestamp + DELIM;
 
  var url:String = adServerURL + userKeyValues + adFormats + cue + playerID + ord;
  return url;
}

Ad Translator クラスでは、ロードとエラーのコールバック関数内で、応答を XML に変換し、setAdXML() を呼び出す必要があります。

広告応答を処理する

fetchAd() 関数内では、通常、広告サーバーを呼び出すのに TranslationURLLoader を使用します。この呼び出しは以下のようになります。

loader.load(url, onAdLoad, onAdLoadError);

load() 呼び出しの最初のパラメータは、以前準備しておいた URL です。onAdLoad と onAdLoadError はそれぞれ、ロードの応答とエラーの応答を処理する関数です。したがって、広告サーバーから返されたデータをパースする、onAdLoad という名前の関数を Ad Translator に作成する必要があります。返されたデータが XML 形式になっていない場合は、データを ActionScript の XML オブジェクトに設定し、setAdXML() を通じてプレーヤに戻す必要があります。Video Cloud プレーヤは、Ad Translator から XML 入力のみを受け入れます。広告 XML は、サポート対象の広告フォーマットで説明されている、予め定義されたサポート対象フォーマットのいずれかである必要があります。広告 XML を組み立てるときには、広告サーバーによっては、いくつかのフィールドが不要な場合があることに注意してください。例えば、OAS では広告が提供されてすぐにインプレッションを追跡するため、サードパーティの追跡に必要なのは trackStartURLs のみです。

広告応答のパース方法は、広告サーバーが応答を返す実際の形式によって異なるため、ここでは説明しません。サンプルの Ad Translator の onAdLoad() 関数は以下のようになっています。

public function onAdLoad(str:String):void {  var xml:XML = null;  try {   xml = new XML(str);  } catch (err:TypeError) {   // 無視。ただし、xml は null になりますtrace("Could not convert ad data into XML.");  }  // 返された XML を Video Cloud の形式に変換した結果は、ここに入れます  // プレーヤに setAdXML(xml) 処理が終了したことを通知; }

onAdLoad() が呼び出されないと、プレーヤはフォーカスを再獲得せず、広告と動画コンテンツは再生されません。注：広告を再生しない場合は、onAdLoad() 呼び出しで null を渡してください。

サードパーティへのリダイレクトを使用

Ad Translator をサードパーティへのリダイレクトと組み合わせて使用し、Video Cloud プレーヤからサードパーティの広告サーバーに対して、さらに別の広告呼び出しをさせることもできます。サードパーティへのリダイレクトは、サーバーサイドまたはクライアントサイドの標準のリダイレクトのことではありません。Video Cloud プレーヤ特有の XML インストラクションです。以下のようになります。

<requestThirdPartyAd translationSWF="http://mysite.com/adtranslator.swf" [trackingPixel="ad_server_impression]">
<optionalArg1>SomeValue</optionalArg1>
<optionalArgN>AnotherValue</optionalArgN>
</requestThirdPartyAd>

広告サーバーは、Video Cloud プレーヤからの広告呼び出しに対する応答の中で、XML インストラクションの <requestThirdPartyAd> を返すことができます。Video Cloud プレーヤに返された応答に、ルートノードとして <requestThirdPartyAd> がある場合、データには広告が含まれておらず、新たな呼び出しを指示するインストラクションが含まれていることがわかります。

サードパーティ広告要求には、オプションの trackingPixel を含めて、希望の数の XML ノードを追加できます。

Ad Translator 内では、AdContextnamedthirdPartyAdXML のプロパティを介して XML にアクセスできます。Ad Translator SWF は指定された広告サーバーに対する完全な広告呼び出しを組み立て、そして XML 応答を待ちます。サードパーティの広告要求が行われるとすぐに、Video Cloud プレーヤは trackingPixel の要求を行います。この trackingPixel は、サードパーティの広告サーバーに送信された広告要求の件数を表すもので、成功した広告インプレッションの件数を追跡したものではありません。

<requestThirdPartyAd> XML は、Ad Translator の処理で使用する他の任意の数のパラメータを含めることができます。例えば、次のような URL のパラメータを挿入できます。

<requestThirdPartyAd translationSWF="http://mysite.com/adtranslator.swf">
http://myadserverURL/mypath/
</requestThirdPartyAd>

この例では、Ad Translator は、次のようなサードパーティ広告 XML から URL 値を取得できます。

override public function fetchAd(context:AdContext):void {
  // requestThirdPartyAd の XML から広告 URL を取得
  var adServerURL:String = context.thirdPartyAdXML.url;
}

次に、XML をパースして、生成された広告要求を適切に修正します。

Video Cloud

App Cloud

リソース

Ad Translator:手順の概要

Ad Translator を使用する

Ad Translator SWF を作成する

Flash Authoring で Ad Translator を作成する

Flex Builder で Ad Translator を作成する

Ad Translator クラスファイル

広告要求を行う

広告応答を処理する

サードパーティへのリダイレクトを使用

会社情報

サポート

デベロッパ

Video Cloud

App Cloud

リソース

Ad Translator を開発する

Ad Translator:手順の概要

Ad Translator を使用する

Ad Translator SWF を作成する

Flash Authoring で Ad Translator を作成する

Flex Builder で Ad Translator を作成する

Ad Translator クラス ファイル

広告要求を行う

広告応答を処理する

サードパーティへのリダイレクトを使用

会社情報

サポート

デベロッパ

Ad Translator クラスファイル