ご利用のアカウントで、Ad トランスレータを使用した統合を実現にするには、以下のようにします。

1. 担当者か Brightcove の営業担当に連絡し、アカウントで Ad トランスレータ を使用できるようにしてもらいます。
2. Ad トランスレータ SWF を作成するの説明に従い、Ad トランスレータ クラスを作成して、SWF にコンパイルします。
3. お持ちのドメインで Ad トランスレータ SWF をホストします。
4. Brightcove カスタマサポートに連絡し、トランスレーション SWF のパスをパブリッシャアカウントに設定してもらいます。サポートお問い合わせフォームを利用して、サポートにお問い合わせいただけます。または、Brightcove Advertising モジュールにおいて、プレーヤレベルで Ad トランスレータ のパスを設定します。詳細は、Ad トランスレータ の URL を設定するを参照してください。

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

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

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

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

Flash Authoring で Ad トランスレータ を作成する

1. Adobe Flash CS3 を使用して、ActionScript の .fla ファイルを新しく作成します。
2. 作成した .fla ファイルと、サンプルの zip ファイル AdTranslatorDevKit.zip から解凍した ExampleTranslator.as と bc_ads.swc を配置するフォルダを作成します。
3. Flash IDE の [Properties] パネルか、または [File] > [Publish Settings] > [Flash] タブ > [Actionscript 3.0 Settings] で、ExampleTranslator.as を Document クラスに設定します。
4. ExampleTranslator.as ファイルを編集し、必要に応じて fetchAd 関数と onAdLoad 関数をお使いの広告サーバに合わせて変更します。
5. 作成したトランスレータの .fla ファイルと同じディレクトリに bc_ads.swc があるのを確認して、.fla をパブリッシュします (CTRL + Enter)。外部ライブラリの bc_ads.swc を使用することで、SWF ファイルのサイズに影響を与える余分の量をインクルードすることなく、広告トランスレータをコンパイルできます。
6. .fla のコンパイルが成功し、作成した .fla ファイルと同じディレクトリに SWF ファイルが出力されます。
7. Ad トランスレータ SWF をプレーヤからアクセス可能な Web サーバ上でホストします。
8. アカウントや任意のプレーヤに、Ad トランスレータ の URL を設定します。

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

Flex Builder で Ad トランスレータ を作成する

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

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

Ad トランスレータ クラスファイル

ExampleTranslator.as について、Ad トランスレータ の基本構造をどのように実装しているか見てみましょう。

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

広告要求を行う

作成する Ad トランスレータ クラスでは、fetchAd() 関数をオーバーライドする必要があります。これは、広告要求を行うための主要な関数です。fetchAd() において、広告 URL を組み立て、com.brightcove.fl.advertising.translation.TranslationURLLoader を使用して広告サーバへ送信します。この関数は同じ形式で組み込む必要がありますが、中身は広告サーバの実装によって変わります。広告が要求されると、プレーヤはこの関数を呼び出して AdContext のインスタンスを渡します。AdContext オブジェクトは、プレーヤの広告要求時点での状態を示すプロパティのコレクションです。動画、キューポイント、キーと値のペアなどのプロパティが含まれています。AdContext オブジェクトで設定できるプロパティの一覧については、『Ad API Reference』の 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;
    }
    
    // cue タイプ: 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 トランスレータ クラスでは、ロードとエラーのコールバック関数内で、応答を XML に変換し、setAdXML() を呼び出す必要があります。

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

loader.load(url, onAdLoad, onAdLoadError);

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

広告応答のパース方法は、広告サーバが応答を返す実際の形式によって異なるため、ここでは説明しません。サンプルの Ad トランスレータ の 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 を Brightcove フォーマットへ変換するのは、ここに記述します。
  
  // 処理が終わったことをプレーヤに通知します。
  setAdXML(xml);
}

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

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

<requestThirdPartyAd
    trackingPixel="[ad_server_impression]"
    translationSWF="path_to_translator_SWF"/>

広告サーバは、Brightcove プレーヤからの広告リクエストに対して、XML インストラクションの <requestThirdPartyAd> を返すことができます。Brightcove プレーヤに返された応答に、ルートノードとして <requestThirdPartyAd> がある場合、データには広告が含まれておらず、新たな呼び出しを指示するインストラクションが含まれていることがわかります。その場合、プレーヤは指定された Ad トランスレータ SWF を呼び出し、オプションの trackingPixel を渡します。Ad トランスレータ SWF は指定された広告サーバに対する完全な広告リクエストを組み立て、そして XML 応答を待ちます。サードパーティの広告要求が行われるとすぐに、Brightcove プレーヤは trackingPixel の要求を行います。この trackingPixel は、サードパーティの広告サーバに送信された広告要求の件数を表すもので、成功した広告インプレッションの件数を追跡したものではありません。

指定された Ad トランスレータ に <requestThirdPartyAd> の XML 応答全体が渡されるため、Ad トランスレータ の処理で使用する他のパラメータも含めることができます。たとえば、広告フォーマットのパラメータ （adFormat=VideoPod など） を挿入することができます。これを Ad トランスレータ がパースし、その結果となる広告要求を適切に変えます。

<requestThirdPartyAd> XML は、広告トランスレータの動作に必要な任意の数のパラメータを含むことができます。例えば、URL用のパラメータを含める場合には、下記のようになります。

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

この場合、下記のような記述で広告トランスレータがサードパーティ製の広告 XML から URL を取得可能です。

override public function fetchAd(context:AdContext):void {
    // Get the ad URL from the XML in requestThirdPartyAd
    var adServerURL:String = context.thirdPartyAdXML.url;
}

その後 XML をパースし、広告リクエストの結果を適切に変更します。