ビデオ コンテンツに広告を表示するShow ads in video content

警告

2020年6月1日から、Microsoft Ad 収益化 platform for Windows UWP アプリがシャットダウンされます。As of June 1, 2020, the Microsoft Ad Monetization platform for Windows UWP apps will be shut down. 詳細情報Learn more

このチュートリアルでは、JavaScript と HTML を使って作成されたユニバーサル Windows プラットフォーム (UWP) アプリのビデオ コンテンツに、AdScheduler クラスを使って広告を表示する方法について説明します。This walkthrough shows how to use the AdScheduler class to show ads in video content in a Universal Windows Platform (UWP) app that was written using JavaScript with HTML.

注意

この機能は現在、JavaScript と HTML を使って作成された UWP アプリでのみサポートされています。This feature is currently supported only for UWP apps that are written using JavaScript with HTML.

AdScheduler は、プログレッシブ メディアとストリーミング メディアの両方で機能し、IAB 標準の Video Ad Serving Template (VAST) 2.0/3.0 と VMAP ペイロード形式を使用します。AdScheduler works with both progressive and streaming media, and uses IAB standard Video Ad Serving Template (VAST) 2.0/3.0 and VMAP payload formats. 標準規格を使用しているため、AdSchedulerは、通信相手の広告サービスに依存しません。By using standards, AdScheduler is agnostic to the ad service with which it interacts.

ビデオ コンテンツの広告は、プログラムが 10 分未満 (短い形式) か、10 分 (長い形式) を超えるかによって異なります。Advertising for video content differs based upon whether the program is under ten minutes (short form), or over ten minutes (long form). 後者は前者よりもサービス上の設定が複雑ですが、クライアント側コードの作成方法にはほとんど違いはありません。Although the latter is more complicated to set up on the service, there is actually no difference in how one writes the client side code. AdScheduler が、マニフェストの代わりに 1 つの広告のみを含む VAST ペイロードを受け取った場合、その VAST ペイロードは 1 つのプリロール広告 (00:00 の時点で再生) についてマニフェストが呼び出された場合と同様に処理されます。If the AdScheduler receives a VAST payload with a single ad instead of a manifest, it is treated as if the manifest called for a single pre-roll ad (one break at time 00:00).

前提条件Prerequisites

  • Visual Studio 2015 以降のリリースと共に Microsoft Advertising SDK をインストールします。Install the Microsoft Advertising SDK with Visual Studio 2015 or a later release.

  • 広告がスケジュールされるビデオ コンテンツを提供するためには、プロジェクトで MediaPlayer コントロールを使う必要があります。Your project must use the MediaPlayer control to serve the video content in which the ads will be scheduled. このコントロールは、Microsoft の GitHub から入手できる TVHelpers コレクションのライブラリにあります。This control is available in the TVHelpers collection of libraries available from Microsoft on GitHub.

    次の例では、HTML マークアップで MediaPlayer を宣言する方法を示します。The following example shows how to declare a MediaPlayer in HTML markup. 通常、このマークアップは index.html ファイル (またはプロジェクトに対応するその他の html ファイル) の <body> セクションに含まれます。Typically, this markup belongs in the <body> section in the index.html file (or another html file as appropriate for your project).

    <div id="MediaPlayerDiv" data-win-control="TVJS.MediaPlayer">
      <video src="URL to your content">
      </video>
    </div>
    

    次の例では、JavaScript コードで MediaPlayer を確立する方法を示します。The following example shows how to establish a MediaPlayer in JavaScript code.

    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 クラスを使用する方法How to use the AdScheduler class in your code

  1. Visual Studio でプロジェクトを開くか、新しいプロジェクトを作ります。In Visual Studio, open your project or create a new project.

  2. プロジェクトのターゲットが [Any CPU] (任意の CPU) になっている場合は、アーキテクチャ固有のビルド出力 (たとえば、[x86]) を使うようにプロジェクトを更新します。If your project targets Any CPU, update your project to use an architecture-specific build output (for example, x86). プロジェクトのターゲットが [Any CPU] (任意の CPU) になっていると、次の手順で Microsoft Advertising ライブラリへの参照を正常に追加できません。If your project targets Any CPU, you will not be able to successfully add a reference to the Microsoft advertising library in the following steps. 詳しくは、「プロジェクトのターゲットを "Any CPU" に設定すると参照エラーが発生する」をご覧ください。For more information, see Reference errors caused by targeting Any CPU in your project.

  3. Microsoft Advertising SDK for JavaScript ライブラリへの参照をプロジェクトに追加します。Add a reference to the Microsoft Advertising SDK for JavaScript library to your project.

    1. [ソリューション エクスプローラー] ウィンドウで、[参照設定] を右クリックし、[参照の追加] を選択します。From the Solution Explorer window, right click References, and select Add Reference…
    2. [参照マネージャー] で、[ユニバーサル Windows] を展開し、[拡張] をクリックして、[Microsoft Advertising SDK for JavaScript] (バージョン 10.0) の横にあるチェック ボックスをオンにします。In Reference Manager, expand Universal Windows, click Extensions, and then select the check box next to Microsoft Advertising SDK for JavaScript (Version 10.0).
    3. [参照マネージャー] で、[OK] をクリックします。In Reference Manager, click OK.
  4. AdScheduler.js ファイルをプロジェクトに追加します。Add the AdScheduler.js file to your project:

    1. Visual Studio で、[プロジェクト][NuGet パッケージの管理] をクリックします。In Visual Studio, click Project and Manage NuGet Packages.
    2. 検索ボックスに、「Microsoft.StoreServices.VideoAdScheduler」と入力し、Microsoft.StoreServices.VideoAdScheduler パッケージをインストールします。In the search box, type Microsoft.StoreServices.VideoAdScheduler and install the Microsoft.StoreServices.VideoAdScheduler package. AdScheduler.js ファイルがプロジェクトの ../js サブディレクトリに追加されます。The AdScheduler.js file is added to the ../js subdirectory in your project.
  5. index.html ファイル (またはプロジェクトに対応するその他の html ファイル) を開きます。Open the index.html file (or other html file as appropriate for your project). <head> セクションで、プロジェクトの default.css と main.js の JavaScript 参照の後に、ad.js と adscheduler.js への参照を追加します。In the <head> section, after the project’s JavaScript references of default.css and main.js, add the reference to ad.js and adscheduler.js.

    <script src="//Microsoft.Advertising.JavaScript/ad.js"></script>
    <script src="/js/adscheduler.js"></script>
    

    注意

    この行は、<head> セクションの main.js のインクルードの後に配置する必要があります。そうでない場合、プロジェクトのビルド時にエラーが発生します。This line must be placed in the <head> section after the include of main.js; otherwise, you will encounter an error when you build your project.

  6. プロジェクトの main.js ファイルで、新しい AdScheduler オブジェクトを作成するコードを追加します。In the main.js file in your project, add code that creates a new AdScheduler object. ビデオ コンテンツをホストする MediaPlayer を渡します。Pass in the MediaPlayer that hosts your video content. このコードは、WinJS.UI.processAll の後に実行されるように配置する必要があります。The code must be placed so that it runs after WinJS.UI.processAll.

    var myMediaPlayer = document.getElementById("MediaPlayerDiv");
    var myAdScheduler = new MicrosoftNSJS.Advertising.AdScheduler(myMediaPlayer);
    
  7. AdScheduler オブジェクトの requestSchedule メソッドまたは requestScheduleByUrl メソッドを使ってサーバーに広告スケジュールを要求し、それを MediaPlayer タイムラインに挿入してから、ビデオ メディアを再生します。Use the requestSchedule or requestScheduleByUrl methods of the AdScheduler object to request an ad schedule from the server and insert it into the MediaPlayer timeline, and then play the video media.

    • Microsoft 広告サーバーに対して広告スケジュールを要求することを許可されている Microsoft パートナーは、requestSchedule を使用して、Microsoft の担当者が提供するアプリケーション ID と広告ユニット ID を指定します。If you are a Microsoft partner who has received permission to request an ad schedule from the Microsoft ad server, use requestSchedule and specify the application ID and ad unit ID that were provided to you by your Microsoft representative.

      このメソッドでは、非同期コンストラクトである Promise の形式を使い、2 つの関数ポインターを渡します。2 つとは、promise の正常完了時に呼び出される onComplete 関数へのポインターと、エラーが発生した場合に呼び出される onError 関数へのポインターです。This method takes the form of a Promise, which is an asynchronous construct where two function pointers are passed: a pointer for the onComplete function to call when the promise completes successfully and a pointer for the onError function to call if an error is encountered. onComplete 関数で、ビデオ コンテンツの再生を開始します。In the onComplete function, start playback of your video content. スケジュールされた時間に広告の再生が始まります。The ad will start playing at the scheduled time. onError 関数では、エラーを処理してからビデオの再生を開始します。In your onError function, handle the error and then start playback of your video. ビデオ コンテンツは広告なしで再生されます。Your video content will play without an ad. onError 関数の引数は、次のメンバーを含むオブジェクトです。The argument of the onError function is an object that contains the following members.

      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 を指定します。To request an ad schedule from a non-Microsoft ad server, use requestScheduleByUrl, and pass in the server URI. このメソッドも Promise の形式を使い、onComplete 関数と onError 関数へのポインターを受け取ります。This method also takes the form of a Promise that accepts pointers for the onComplete and onError functions. サーバーから返される広告ペイロードは、Video Ad Serving Template (VAST) または Video Multiple Ad Playlist (VMAP) ペイロード形式に準拠している必要があります。The ad payload that is returned from the server must conform to the Video Ad Serving Template (VAST) or Video Multiple Ad Playlist (VMAP) payload formats.

      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 が戻るまで待機する必要があります。You should wait for requestSchedule or requestScheduleByUrl to return before starting to play the primary video content in the MediaPlayer. requestSchedule が戻る前にメディアの再生を開始すると (プリロール広告の場合)、プリロールによってメインのビデオ コンテンツが中断されます。Starting to play media before requestSchedule returns (in the case of a pre-roll advertisement) will result in the pre-roll interrupting the primary video content. 関数が失敗した場合でも、play を呼び出す必要があります。AdScheduler は、広告をスキップしてコンテンツに直接移動するように MediaPlayer に通知するためです。You must call play even if the function fails, because the AdScheduler will tell the MediaPlayer to skip the ad(s) and move straight to the content. ビジネス要件によっては、広告がリモートで正常に取得できない場合に、ビルトイン広告を挿入するなどの処理を行うこともできます。You may have a different business requirement, such as inserting a built-in ad if an ad can't be successfully fetched remotely.

  8. 再生中に、アプリが進行状況や、最初の広告マッチング プロセス後に発生したエラーを追跡するための追加のイベントを処理できます。During playback, you can handle additional events that let your app track progress and/or errors which may occur after the initial ad matching process. 次のコードでは、これらのイベントのいくつか (onPodStartonPodEndonPodCountdownonAdProgressonAllComplete、および onErrorOccurred) を示します。The following code shows some of these events, including onPodStart, onPodEnd, onPodCountdown, onAdProgress, onAllComplete, and 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 members

このセクションでは、AdScheduler オブジェクトのメンバーについて説明します。This section provides some details about the members of the AdScheduler object. これらのメンバーについて詳しくは、プロジェクトに含まれている AdScheduler.js ファイル内のコメントと定義をご覧ください。For more information about these members, see the comments and definitions in the AdScheduler.js file in your project.

requestSchedulerequestSchedule

このメソッドは、Microsoft 広告サーバーに広告スケジュールを要求し、それを AdScheduler コンストラクターに渡された MediaPlayer のタイムラインに挿入します。This method requests an ad schedule from the Microsoft ad server and inserts it into the timeline of the MediaPlayer that was passed to the AdScheduler constructor.

省略可能な第 3 パラメーター (adTags) は、名前と値のペアを含む JSON コレクションで、高度なターゲット設定を必要とするアプリで使用できます。The optional third paramter (adTags) is a JSON collection of name/value pairs that can be used for apps that have advanced targeting. たとえば、自動車関連のさまざまなビデオを再生するアプリでは、広告ユニット ID に加えて、表示する自動車のメーカーとモデルを渡すことができます。For example, an app that plays a variety of auto-related videos might supplement the ad unit ID with the make and model of the car being shown. このパラメーターは、広告タグの使用について Microsoft から承認を受けたパートナーのみが使うことを想定しています。This parameter is intended to be used only by partners who receive approval from Microsoft to use ad tags.

adTags を参照するときは次の点に注意する必要があります。The following items should be noted when referring to adTags:

  • このパラメーターはほとんど使用されないオプションです。This parameter is a very rarely used option. 発行元は、adTags を使用する前に Microsoft とよく相談する必要があります。The publisher must work closely with Microsoft before using adTags.
  • 名前と値はどちらも、広告サービスで事前に決定されている必要があります。Both the names and the values must be predetermined on the ad service. 広告タグは自由な検索用語やキーワードではありません。Ad tags are not open ended search terms or keywords.
  • サポートされている最大のタグ数は 10 です。The maximum supported number of tags is 10.
  • タグ名は 16 文字に制限されています。Tag names are restricted to 16 characters.
  • タグの値は最大 128 文字です。Tag values have a maximum of 128 characters.

requestScheduleByUrirequestScheduleByUri

このメソッドは、URI で指定された Microsoft 以外の広告サーバーに広告スケジュールを要求し、それを AdScheduler コンストラクターに渡された MediaPlayer のタイムラインに挿入します。This method requests an ad schedule from the non-Microsoft ad server specified in the URI and inserts it into the timeline of the MediaPlayer that was passed to the AdScheduler constructor. 広告サーバーから返される広告ペイロードは、Video Ad Serving Template (VAST) または Video Multiple Ad Playlist (VMAP) ペイロード形式に準拠している必要があります。The ad payload that is returned by the ad server must conform to the Video Ad Serving Template (VAST) or Video Multiple Ad Playlist (VMAP) payload formats.

mediaTimeoutmediaTimeout

このプロパティは、メディアを再生可能にする時間をミリ秒単位で取得または設定します。This property gets or sets the number of milliseconds that the media must be playable. 値 0 は、タイムアウトしないようにシステムに通知します。A value of 0 informs the system to never timeout. 既定値は 30000 ミリ秒 (30 秒) です。The default is 30000 ms (30 seconds).

playSkippedMediaplaySkippedMedia

このプロパティは、スケジュールされた開始時間よりも先の位置までユーザーがスキップした場合に、スケジュールされたメディアを再生するかどうかを示すブール値を取得または設定します。This property gets or sets a Boolean value that indicates whether scheduled media will play if user skips ahead to a point past a scheduled start time.

メインのビデオ コンテンツの早送り中や巻き戻し中の広告の動作については、広告クライアントとメディア プレイヤーによってルールが適用されます。The ad client and media player will enforce rules in terms what happens to advertisements during fast forwarding and rewinding of the primary video content. 通常、アプリ開発者は広告を完全にスキップできるようにはしませんが、妥当なエクスペリエンスをユーザーに提供することを望みます。In most cases, app developers do not allow advertisements to be entirely skipped over but do want to provide a reasonable experience for the user. 次の 2 つのオプションは、ほとんどの開発者のニーズに対応します。The following two options fall within the needs of most developers:

  1. エンド ユーザーが自由に広告ポッドをスキップできるようにします。Allow end-users to skip over advertisement pods at will.
  2. ユーザーが広告ポッドをスキップできるようにしますが、再生を再開するときは最後のポッドを再生します。Allow users to skip over advertisement pods but play the most recent pod when playback resumes.

playSkippedMedia プロパティには次の条件があります。The playSkippedMedia property has the following conditions:

  • いったん広告が開始されたら、広告をスキップしたり早送りしたりできない。Advertisements cannot be skipped or fast forwarded once the advertisement begins.
  • いったんポッドが開始されたら、広告ポッド内のすべての広告を再生する。All advertisements in an advertisement pod will play once the pod has started.
  • いったん再生されたら、メインのコンテンツ (映画、エピソードなど) の間は広告を再び再生しない。広告マーカーは再生済みまたは削除済みとマークされる。Once played, an advertisement will not play again during the primary content (movie, episode, etc.); advertisement markers will be marked as played or removed.
  • プリロール広告はスキップできない。Pre-rollout advertisements cannot be skipped.

広告を含んでいるコンテンツを再開するときは、playSkippedMediafalse に設定することで、プリロール広告をスキップして最新の広告ブレークの再生を回避します。When resuming content that contains advertising, set playSkippedMedia to false to skip pre-rolls and prevent the most recent ad break from playing. 次に、コンテンツの開始後に playSkippedMediatrue に設定して、ユーザーが後続の広告を早送りできないようにします。Then, after the content starts, set playSkippedMedia to true to ensure that users cannot fast-forward through subsequent ads.

注意

ポッドとは、連続して再生される広告のグループです。広告ブレークの間に再生される広告のグループなどがあります。A pod is a group of ads that play in a sequence, such as a group of ads that play during a commercial break. 詳しくは、IAB Digital Video Ad Serving Template (VAST) の仕様をご覧ください。For more details, see the IAB Digital Video Ad Serving Template (VAST) specification.

requestTimeoutrequestTimeout

このプロパティは、広告要求の応答がタイムアウトするまでの待ち時間をミリ秒単位で取得または設定します。値 0 は、タイムアウトしないようにシステムに通知します。This property gets or sets the number of milliseconds to wait for an ad request response before timing out. A value of 0 informs the system to never timeout. 既定値は 30000 ミリ秒 (30 秒) です。The default is 30000 ms (30 seconds).

scheduleschedule

このプロパティは、広告サーバーから受け取ったスケジュール データを取得します。This property gets the schedule data that was retrieved from the ad server. このオブジェクトには、Video Ad Serving Template (VAST) または Video Multiple Ad Playlist (VMAP) ペイロードの構造に対応する完全なデータ階層が含まれます。This object includes the full hierarchy of data that corresponds to the structure of the Video Ad Serving Template (VAST) or Video Multiple Ad Playlist (VMAP) payload.

onAdProgressonAdProgress

このイベントは、広告の再生が 4 分の 1 ごとのチェックポイントに到達したときに発生します。This event is raised when ad playback reaches quartile checkpoints. イベント ハンドラーの第 2 パラメーター (eventInfo) は、次のメンバーを含む JSON オブジェクトです。The second parameter of the event handler (eventInfo) is a JSON object with the following members:

  • progress: 広告の再生状態 (AdScheduler.js に定義されている MediaProgress 列挙型の値のいずれか)。progress: The ad playback status (one of the MediaProgress enum values defined in AdScheduler.js).
  • clip: 再生中のビデオ クリップ。clip: The video clip that is being played. このオブジェクトは、ユーザーのコードで使用するためのものではありません。This object is not intended to be used in your code.
  • adPackage: 再生中の広告に対応する広告ペイロードの部分を表すオブジェクト。adPackage: An object that represents the part of the ad payload that corresponds to the ad that is playing. このオブジェクトは、ユーザーのコードで使用するためのものではありません。This object is not intended to be used in your code.

onAllCompleteonAllComplete

このイベントは、メイン コンテンツが終了し、スケジュールされたポストロール広告も終了したときに発生します。This event is raised when the main content reaches the end and any scheduled post-roll ads are also ended.

onErrorOccurredonErrorOccurred

このイベントは、AdScheduler でエラーが発生したときに生成されます。This event is raised when the AdScheduler encounters an error. エラー コードの値について詳しくは、「ErrorCode」をご覧ください。For more information about the error code values, see ErrorCode.

onPodCountdownonPodCountdown

このイベントは、広告の再生中に発生し、現在のポッドの残り時間を通知します。This event is raised when an ad is playing and indicates how much time remains in the current pod. イベント ハンドラーの第 2 パラメーター (eventData) は、次のメンバーを含む JSON オブジェクトです。The second parameter of the event handler (eventData) is a JSON object with the following members:

  • remainingAdTime: 現在の広告の残り時間を示す秒数。remainingAdTime: The number of seconds left for the current ad.
  • remainingPodTime: 現在のポッドの残り時間を示す秒数。remainingPodTime: The number of seconds left for the current pod.

注意

ポッドとは、連続して再生される広告のグループです。広告ブレークの間に再生される広告のグループなどがあります。A pod is a group of ads that play in a sequence, such as a group of ads that play during a commercial break. 詳しくは、IAB Digital Video Ad Serving Template (VAST) の仕様をご覧ください。For more details, see the IAB Digital Video Ad Serving Template (VAST) specification.

onPodEndonPodEnd

このイベントは、広告ポッドが終了したときに発生します。This event is raised when an ad pod ends. イベント ハンドラーの第 2 パラメーター (eventData) は、次のメンバーを含む JSON オブジェクトです。The second parameter of the event handler (eventData) is a JSON object with the following members:

  • startTime: ポッドの開始時間 (秒単位)。startTime: The pod's start time, in seconds.
  • pod: ポッドを表すオブジェクト。pod: An object that represents the pod. このオブジェクトは、ユーザーのコードで使用するためのものではありません。This object is not intended to be used in your code.

onPodStartonPodStart

このイベントは、広告ポッドが開始されたときに発生します。This event is raised when an ad pod starts. イベント ハンドラーの第 2 パラメーター (eventData) は、次のメンバーを含む JSON オブジェクトです。The second parameter of the event handler (eventData) is a JSON object with the following members:

  • startTime: ポッドの開始時間 (秒単位)。startTime: The pod's start time, in seconds.
  • pod: ポッドを表すオブジェクト。pod: An object that represents the pod. このオブジェクトは、ユーザーのコードで使用するためのものではありません。This object is not intended to be used in your code.