ビデオコンテンツに広告を表示する

[アーティクル]
03/18/2023

警告

2020 年 6 月 1 日以降、Windows UWP アプリ用の Microsoft の広告の収益化プラットフォームはシャットダウンされます。詳細情報

このチュートリアルでは、JavaScript と HTML を使って作成されたユニバーサル Windows プラットフォーム (UWP) アプリのビデオコンテンツに、AdScheduler クラスを使って広告を表示する方法について説明します。

注意

この機能は現在、JavaScript と HTML を使って作成された UWP アプリでのみサポートされています。

AdScheduler は、プログレッシブメディアとストリーミングメディアの両方で機能し、IAB 標準の Video Ad Serving Template (VAST) 2.0/3.0 と VMAP ペイロード形式を使用します。標準規格を使用しているため、AdSchedulerは、通信相手の広告サービスに依存しません。

ビデオコンテンツの広告は、プログラムが 10 分未満 (短い形式) か、10 分 (長い形式) を超えるかによって異なります。後者は前者よりもサービス上の設定が複雑ですが、クライアント側コードの作成方法にはほとんど違いはありません。 AdScheduler が、マニフェストの代わりに 1 つの広告のみを含む VAST ペイロードを受け取った場合、その VAST ペイロードは 1 つのプリロール広告 (00:00 の時点で再生) についてマニフェストが呼び出された場合と同様に処理されます。

前提条件

Visual Studio 2015 以降のリリースと共に Microsoft Advertising SDK をインストールします。
広告がスケジュールされるビデオコンテンツを提供するためには、プロジェクトで MediaPlayer コントロールを使う必要があります。このコントロールは、Microsoft の GitHub から入手できる TVHelpers コレクションのライブラリにあります。

次の例では、HTML マークアップで MediaPlayer を宣言する方法を示します。通常、このマークアップは index.html ファイル (またはプロジェクトに対応するその他の html ファイル) の <body> セクションに含まれます。
```
<div id="MediaPlayerDiv" data-win-control="TVJS.MediaPlayer">
  <video src="URL to your content">
  </video>
</div>
```
次の例では、JavaScript コードで MediaPlayer を確立する方法を示します。
```
var mediaPlayerDiv = document.createElement("div");
document.body.appendChild(mediaPlayerDiv);

var videoElement = document.createElement("video");
videoElement.src = "<URL to your content>";
mediaPlayerDiv.appendChild(videoElement);

var mediaPlayer = new TVJS.MediaPlayer(mediaPlayerDiv);
```

コードで AdScheduler クラスを使用する方法

Visual Studio でプロジェクトを開くか、新しいプロジェクトを作ります。
プロジェクトのターゲットが [Any CPU] (任意の CPU) になっている場合は、アーキテクチャ固有のビルド出力 (たとえば、[x86]) を使うようにプロジェクトを更新します。プロジェクトのターゲットが [Any CPU] (任意の CPU) になっていると、次の手順で Microsoft Advertising ライブラリへの参照を正常に追加できません。詳しくは、「プロジェクトのターゲットを "Any CPU" に設定すると参照エラーが発生する」をご覧ください。
Microsoft Advertising SDK for JavaScript ライブラリへの参照をプロジェクトに追加します。
1. [ソリューションエクスプローラー] ウィンドウで、[参照設定] を右クリックし、[参照の追加] を選択します。
2. [参照マネージャー] で、[ユニバーサル Windows] を展開し、[拡張] をクリックして、[Microsoft Advertising SDK for JavaScript] (バージョン 10.0) の横にあるチェックボックスをオンにします。
3. [参照マネージャー] で、[OK] をクリックします。
AdScheduler.js ファイルをプロジェクトに追加します。
1. Visual Studio で、[プロジェクト] と [NuGet パッケージの管理] をクリックします。
2. 検索ボックスに、「Microsoft.StoreServices.VideoAdScheduler」と入力し、Microsoft.StoreServices.VideoAdScheduler パッケージをインストールします。 AdScheduler.js ファイルがプロジェクトの ../js サブディレクトリに追加されます。
index.html ファイル (またはプロジェクトに対応するその他の html ファイル) を開きます。 <head> セクションで、プロジェクトの default.css と main.js の JavaScript 参照の後に、ad.js と adscheduler.js への参照を追加します。
```
<script src="//Microsoft.Advertising.JavaScript/ad.js"></script>
<script src="/js/adscheduler.js"></script>
```
注意

この行は、<head> セクションの main.js のインクルードの後に配置する必要があります。そうでない場合、プロジェクトのビルド時にエラーが発生します。
プロジェクトの main.js ファイルで、新しい AdScheduler オブジェクトを作成するコードを追加します。ビデオコンテンツをホストする MediaPlayer を渡します。このコードは、WinJS.UI.processAll の後に実行されるように配置する必要があります。
```
var myMediaPlayer = document.getElementById("MediaPlayerDiv");
var myAdScheduler = new MicrosoftNSJS.Advertising.AdScheduler(myMediaPlayer);
```
AdScheduler オブジェクトの requestSchedule メソッドまたは requestScheduleByUrl メソッドを使ってサーバーに広告スケジュールを要求し、それを MediaPlayer タイムラインに挿入してから、ビデオメディアを再生します。
- Microsoft 広告サーバーに対して広告スケジュールを要求することを許可されている Microsoft パートナーは、requestSchedule を使用して、Microsoft の担当者が提供するアプリケーション ID と広告ユニット ID を指定します。
  
  このメソッドでは、非同期コンストラクトである Promise の形式を使い、2 つの関数ポインターを渡します。2 つとは、promise の正常完了時に呼び出される onComplete 関数へのポインターと、エラーが発生した場合に呼び出される onError 関数へのポインターです。 onComplete 関数で、ビデオコンテンツの再生を開始します。スケジュールされた時間に広告の再生が始まります。 onError 関数では、エラーを処理してからビデオの再生を開始します。ビデオコンテンツは広告なしで再生されます。 onError 関数の引数は、次のメンバーを含むオブジェクトです。
```
myAdScheduler.requestSchedule("your application ID", "your ad unit ID").then(
  function promiseSuccessHandler(schedule) {
      // Success: play the video content with the scheduled ads.
      myMediaPlayer.tvControl.play();
  },
  function promiseErrorHandler(err) {
      // Error: play the video content without the ads.
      myMediaPlayer.tvControl.play();
  });
```
- Microsoft 以外の広告サーバーに広告スケジュールを要求するには、requestScheduleByUrl を使用し、サーバー URI を指定します。このメソッドも Promise の形式を使い、onComplete 関数と onError 関数へのポインターを受け取ります。サーバーから返される広告ペイロードは、Video Ad Serving Template (VAST) または Video Multiple Ad Playlist (VMAP) ペイロード形式に準拠している必要があります。
```
myAdScheduler.requestScheduleByUrl("your URL").then(
  function promiseSuccessHandler(schedule) {
      // Success: play the video content with the scheduled ads.
      myMediaPlayer.winControl.play();
  },
  function promiseErrorHandler(evt) {
      // Error: play the video content without the ads.
      myMediaPlayer.winControl.play();
  });
```
注意

MediaPlayer でメインのビデオコンテンツの再生を開始する前に、requestSchedule または requestScheduleByUrl が戻るまで待機する必要があります。 requestSchedule が戻る前にメディアの再生を開始すると (プリロール広告の場合)、プリロールによってメインのビデオコンテンツが中断されます。関数が失敗した場合でも、play を呼び出す必要があります。AdScheduler は、広告をスキップしてコンテンツに直接移動するように MediaPlayer に通知するためです。ビジネス要件によっては、広告がリモートで正常に取得できない場合に、ビルトイン広告を挿入するなどの処理を行うこともできます。

再生中に、アプリが進行状況や、最初の広告マッチングプロセス後に発生したエラーを追跡するための追加のイベントを処理できます。次のコードでは、これらのイベントのいくつか (onPodStart、onPodEnd、onPodCountdown、onAdProgress、onAllComplete、および onErrorOccurred) を示します。

// Raised when an ad pod starts. Make the countdown timer visible.
myAdScheduler.onPodStart = function (sender, data) {
    myCounterDiv.style.visibility = "visible";
}

// Raised when an ad pod ends. Hide the countdown timer.
myAdScheduler.onPodEnd = function (sender, data) {
    myCounterDiv.style.visibility = "hidden";
}

// Raised when an ad is playing and indicates how many seconds remain  
// in the current pod of ads. This is useful when the app wants to show 
// a visual countdown until the video content resumes.
myAdScheduler.onPodCountdown = function (sender, data) {
    myCounterText = "Content resumes in: " +
    Math.ceil(data.remainingPodTime) + " seconds.";
}

// Raised during each quartile of progress through the ad clip.
myAdScheduler.onAdProgress = function (sender, data) {
}

// Raised when the ads and content are complete.
myAdScheduler.onAllComplete = function (sender) {
}

// Raised when an error occurs during playback after successfully scheduling.
myAdScheduler.onErrorOccurred = function (sender, data) {
}

AdScheduler のメンバー

このセクションでは、AdScheduler オブジェクトのメンバーについて説明します。これらのメンバーについて詳しくは、プロジェクトに含まれている AdScheduler.js ファイル内のコメントと定義をご覧ください。

requestSchedule

このメソッドは、Microsoft 広告サーバーに広告スケジュールを要求し、それを AdScheduler コンストラクターに渡された MediaPlayer のタイムラインに挿入します。

省略可能な第 3 パラメーター (adTags) は、名前と値のペアを含む JSON コレクションで、高度なターゲット設定を必要とするアプリで使用できます。たとえば、自動車関連のさまざまなビデオを再生するアプリでは、広告ユニット ID に加えて、表示する自動車のメーカーとモデルを渡すことができます。このパラメーターは、広告タグの使用について Microsoft から承認を受けたパートナーのみが使うことを想定しています。

adTags を参照するときは次の点に注意する必要があります。

このパラメーターはほとんど使用されないオプションです。発行元は、adTags を使用する前に Microsoft とよく相談する必要があります。
名前と値はどちらも、広告サービスで事前に決定されている必要があります。広告タグは自由な検索用語やキーワードではありません。
サポートされている最大のタグ数は 10 です。
タグ名は 16 文字に制限されています。
タグの値は最大 128 文字です。

requestScheduleByUri

このメソッドは、URI で指定された Microsoft 以外の広告サーバーに広告スケジュールを要求し、それを AdScheduler コンストラクターに渡された MediaPlayer のタイムラインに挿入します。広告サーバーから返される広告ペイロードは、Video Ad Serving Template (VAST) または Video Multiple Ad Playlist (VMAP) ペイロード形式に準拠している必要があります。

mediaTimeout

このプロパティは、メディアを再生可能にする時間をミリ秒単位で取得または設定します。値 0 は、タイムアウトしないようにシステムに通知します。既定値は 30000 ミリ秒 (30 秒) です。

playSkippedMedia

このプロパティは、スケジュールされた開始時間よりも先の位置までユーザーがスキップした場合に、スケジュールされたメディアを再生するかどうかを示すブール値を取得または設定します。

メインのビデオコンテンツの早送り中や巻き戻し中の広告の動作については、広告クライアントとメディアプレイヤーによってルールが適用されます。通常、アプリ開発者は広告を完全にスキップできるようにはしませんが、妥当なエクスペリエンスをユーザーに提供することを望みます。次の 2 つのオプションは、ほとんどの開発者のニーズに対応します。

エンドユーザーが自由に広告ポッドをスキップできるようにします。
ユーザーが広告ポッドをスキップできるようにしますが、再生を再開するときは最後のポッドを再生します。

playSkippedMedia プロパティには次の条件があります。

いったん広告が開始されたら、広告をスキップしたり早送りしたりできない。
いったんポッドが開始されたら、広告ポッド内のすべての広告を再生する。
いったん再生されたら、メインのコンテンツ (映画、エピソードなど) の間は広告を再び再生しない。広告マーカーは再生済みまたは削除済みとマークされる。
プリロール広告はスキップできない。

広告を含んでいるコンテンツを再開するときは、playSkippedMedia を false に設定することで、プリロール広告をスキップして最新の広告ブレークの再生を回避します。次に、コンテンツの開始後に playSkippedMedia を true に設定して、ユーザーが後続の広告を早送りできないようにします。

注意

ポッドとは、連続して再生される広告のグループです。広告ブレークの間に再生される広告のグループなどがあります。詳しくは、IAB Digital Video Ad Serving Template (VAST) の仕様をご覧ください。

requestTimeout

このプロパティは、広告要求の応答がタイムアウトするまでの待ち時間をミリ秒単位で取得または設定します。値 0 は、タイムアウトしないようにシステムに通知します。既定値は 30000 ミリ秒 (30 秒) です。

schedule

このプロパティは、広告サーバーから受け取ったスケジュールデータを取得します。このオブジェクトには、Video Ad Serving Template (VAST) または Video Multiple Ad Playlist (VMAP) ペイロードの構造に対応する完全なデータ階層が含まれます。

onAdProgress

このイベントは、広告の再生が 4 分の 1 ごとのチェックポイントに到達したときに発生します。イベントハンドラーの第 2 パラメーター (eventInfo) は、次のメンバーを含む JSON オブジェクトです。

progress: 広告の再生状態 (AdScheduler.js に定義されている MediaProgress 列挙型の値のいずれか)。
clip: 再生中のビデオクリップ。このオブジェクトは、ユーザーのコードで使用するためのものではありません。
adPackage: 再生中の広告に対応する広告ペイロードの部分を表すオブジェクト。このオブジェクトは、ユーザーのコードで使用するためのものではありません。

onAllComplete

このイベントは、メインコンテンツが終了し、スケジュールされたポストロール広告も終了したときに発生します。

onErrorOccurred

このイベントは、AdScheduler でエラーが発生したときに生成されます。エラーコードの値について詳しくは、「ErrorCode」をご覧ください。

onPodCountdown

このイベントは、広告の再生中に発生し、現在のポッドの残り時間を通知します。イベントハンドラーの第 2 パラメーター (eventData) は、次のメンバーを含む JSON オブジェクトです。

remainingAdTime: 現在の広告の残り時間を示す秒数。
remainingPodTime: 現在のポッドの残り時間を示す秒数。

注意

onPodEnd

このイベントは、広告ポッドが終了したときに発生します。イベントハンドラーの第 2 パラメーター (eventData) は、次のメンバーを含む JSON オブジェクトです。

startTime: ポッドの開始時間 (秒単位)。
pod: ポッドを表すオブジェクト。このオブジェクトは、ユーザーのコードで使用するためのものではありません。

onPodStart

このイベントは、広告ポッドが開始されたときに発生します。イベントハンドラーの第 2 パラメーター (eventData) は、次のメンバーを含む JSON オブジェクトです。

startTime: ポッドの開始時間 (秒単位)。
pod: ポッドを表すオブジェクト。このオブジェクトは、ユーザーのコードで使用するためのものではありません。

ビデオコンテンツに広告を表示する

前提条件

コードで AdScheduler クラスを使用する方法

AdScheduler のメンバー

requestSchedule

requestScheduleByUri

mediaTimeout

playSkippedMedia

requestTimeout

schedule

onAdProgress

onAllComplete

onErrorOccurred

onPodCountdown

onPodEnd

onPodStart

フィードバック

フィードバック

その他のリソース

ビデオ コンテンツに広告を表示する

前提条件

コードで AdScheduler クラスを使用する方法

AdScheduler のメンバー

requestSchedule

requestScheduleByUri

mediaTimeout

playSkippedMedia

requestTimeout

schedule

onAdProgress

onAllComplete

onErrorOccurred

onPodCountdown

onPodEnd

onPodStart

フィードバック

フィードバック

その他のリソース

ビデオコンテンツに広告を表示する