始める

IMA SDK を使用すると、マルチメディア広告をウェブサイトやアプリに簡単に統合できます。IMA SDK では、 VAST 準拠の広告サーバーから広告をリクエストし、アプリ内での広告再生を管理できます。IMA クライアントサイド SDK を使用すると、SDK が広告再生を処理する一方で、コンテンツの動画再生のコントロールを維持できます。広告は、アプリのコンテンツ動画プレーヤーの上部にある別の動画プレーヤー内で再生されます。

このガイドでは、IMA SDK をシンプルな動画プレーヤー アプリに統合する方法について説明します。統合の完了したサンプルを確認する場合は、GitHub から簡単なサンプルをダウンロードしてください。SDK が統合されている HTML5 プレーヤーに関心をお持ちの場合は、Video.js 用 IMA SDK プラグインをご覧ください。

IMA クライアントサイドの概要

IMA クライアントサイドの実装には、このガイドで説明する次の 4 つの主要な SDK コンポーネントが必要です。

  • AdDisplayContainer: 広告がレンダリングされるコンテナ オブジェクト。
  • AdsLoader: 広告をリクエストし、広告リクエスト レスポンスからのイベントを処理するオブジェクト。アプリケーションのライフサイクル全体で再利用できる広告ローダーは 1 つのみインスタンス化する必要があります。
  • AdsRequest: 広告リクエストを定義するオブジェクト。広告リクエストでは、VAST 広告タグの URL に加え、広告サイズなどの追加のパラメータも指定します。
  • AdsManager: 広告リクエストへのレスポンスを格納し、広告の再生を制御し、SDK によって発生した広告イベントをリッスンするオブジェクト。

前提条件

始める前に、次のものが必要になります。

  • 空のファイルが 3 つある
    • index.html
    • style.css
    • ads.js
  • テストに使用するコンピュータまたはウェブサーバーにインストールされた Python

1. 開発サーバーを起動する

IMA SDK は読み込み元のページと同じプロトコルを介して依存関係を読み込むため、ウェブサーバーを使用してアプリをテストする必要があります。ローカルの開発環境サーバーを起動する最も簡単な方法は Python の組み込みサーバーを使用することです。

  1. 次のコマンドラインを使用して、index.html ファイルを含むディレクトリから次のコマンドを実行します。
      python -m http.server 8000
    
  2. ウェブブラウザで http://localhost:8000/ にアクセスします。

Apache HTTP Server などの他のウェブサーバーを使用することもできます。

2. シンプルな動画プレーヤーを作成する

まず、index.html を変更して、折り返し要素に含まれるシンプルな HTML5 動画要素と、再生をトリガーするボタンを作成します。また、style.css ファイルと ads.js ファイルを読み込むために必要なタグも追加します。次に、styles.css を変更して、動画プレーヤーがモバイル デバイスに対してレスポンシブになるようにします。最後に、ads.js で、再生ボタンがクリックされたときに動画の再生をトリガーします。

index.html

<!doctype html>
<html lang="en">
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <div id="page-content">
      <div id="video-container">
        <video id="video-element">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="ads.js"></script>
  </body>
</html>

style.css
#page-content {
  position: relative;
  /* this element's width controls the effective height */
  /* of the video container's padding-bottom */
  max-width: 640px;
  margin: 10px auto;
}

#video-container {
  position: relative;
  /* forces the container to match a 16x9 aspect ratio */
  /* replace with 75% for a 4:3 aspect ratio, if needed */
  padding-bottom: 56.25%;
}

#video-element {
  /* forces the contents to fill the container */
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}
ads.js
var videoElement;

// On window load, attach an event to the play button click
// that triggers playback on the video element
window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

この手順を完了すると、開発サーバーを介してブラウザで index.html を開くと、動画要素が表示され、再生ボタンをクリックすると動画が開始されるはずです。

3. IMA SDK をインポートする

次に、index.html のスクリプトタグを使用して IMA フレームワークを ads.js のタグの前に追加します。

index.html
...

        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

4. ページと動画プレーヤーのハンドラをアタッチする

JavaScript を使用して動画プレーヤーの動作を変更するには、以下のアクションをトリガーするイベント ハンドラを追加します。

  • ページの読み込みが完了したら、IMA SDK を初期化します。
  • 動画の再生ボタンがクリックされたら、広告を読み込みます(広告がすでに読み込まれている場合を除く)。
  • ブラウザ ウィンドウのサイズが変更されたら、動画要素と adsManager のサイズを更新して、ページがモバイル デバイスに対してレスポンシブになるようにします。
ads.js
var videoElement;
// Define a variable to track whether there are ads loaded and initially set it to false
var adsLoaded = false;

window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  initializeIMA();
  videoElement.addEventListener('play', function(event) {
    loadAds(event);
  });
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

window.addEventListener('resize', function(event) {
  console.log("window resized");
});

function initializeIMA() {
  console.log("initializing IMA");
}

function loadAds(event) {
  // Prevent this function from running on if there are already ads loaded
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // Prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");
}

5. 広告コンテナを作成する

ほとんどのブラウザで、IMA SDK は広告と広告関連の UI 要素の両方を表示するために専用の広告コンテナ要素を使用します。このコンテナは、動画要素を左上隅から重ねるサイズにする必要があります。このコンテナに配置される広告の高さと幅は、adsManager オブジェクトによって設定されるため、これらの値を手動で設定する必要はありません。

この広告コンテナ要素を実装するには、まず video-container 要素内に新しい div を作成します。次に、CSS を更新して、要素を video-element の左上隅に配置します。最後に、ページの読み込み時に実行される initializeIMA() 関数内でコンテナの変数を定義します。

index.html
...

  <div id="video-container">
    <video id="video-element" controls>
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
    </video>
    <div id="ad-container"></div>
  </div>

...
style.css
...

#ad-container {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
}
ads.js
var videoElement;
var adsLoaded = false;
var adContainer;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
}

6. AdsLoader を初期化して広告リクエストを行う

一連の広告をリクエストするには、ima.AdsLoader インスタンスを作成します。このインスタンスは入力として AdDisplayContainer オブジェクトを受け取り、指定された広告タグ URL に関連付けられている ima.AdsRequest オブジェクトを処理するために使用できます。この例で使用されている広告タグには、10 秒間のプレロール広告が含まれています。IMA Video Suite Inspector を使用して、この URL または任意の広告タグ URL をテストできます。

ima.AdsLoader のインスタンスは、ページのライフサイクル全体で 1 つだけ維持することをおすすめします。広告リクエストを追加するには、新しい ima.AdsRequest オブジェクトを作成し、同じ ima.AdsLoader を再利用します。詳細については、IMA SDK に関するよくある質問をご覧ください。

ads.js
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

  // Let the AdsLoader know when the video has ended
  videoElement.addEventListener('ended', function() {
    adsLoader.contentComplete();
  });

  var adsRequest = new google.ima.AdsRequest();
  adsRequest.adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' +
      'iu=/21775744923/external/single_ad_samples&sz=640x480&' +
      'cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&' +
      'gdfp_req=1&output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=';

  // Specify the linear and nonlinear slot sizes. This helps the SDK to
  // select the correct creative if multiple are returned.
  adsRequest.linearAdSlotWidth = videoElement.clientWidth;
  adsRequest.linearAdSlotHeight = videoElement.clientHeight;
  adsRequest.nonLinearAdSlotWidth = videoElement.clientWidth;
  adsRequest.nonLinearAdSlotHeight = videoElement.clientHeight / 3;

  // Pass the request to the adsLoader to request ads
  adsLoader.requestAds(adsRequest);
}

7. AdsLoader イベントをリッスンする

広告が正常に読み込まれると、ima.AdsLoader から ADS_MANAGER_LOADED イベントが発生します。コールバックに渡されたイベントを解析し、AdsManager オブジェクトを初期化します。AdsManager は、広告タグ URL へのレスポンスで定義されている個々の広告を読み込みます。

また、読み込みプロセス中に発生する可能性のあるすべてのエラーに必ず対応してください。広告が読み込まれない場合は、ユーザー エクスペリエンスを妨げないように、広告なしでメディアの再生を続行してください。

ads.js
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;
var adsManager;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded,
      false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError,
      false);

...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Instantiate the AdsManager from the adsLoader response and pass it the video element
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);
}

function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  if(adsManager) {
    adsManager.destroy();
  }
}

8. AdsManager を起動する

広告の再生を開始するには、AdsManager を開始する必要があります。モバイル ブラウザを完全にサポートするには、ユーザーの操作によってトリガーされる必要があります。

ads.js
...

function loadAds(event) {
  // prevent this function from running on every play event
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");

  // Initialize the container. Must be done via a user action on mobile devices.
  videoElement.load();
  adDisplayContainer.initialize();

  var width = videoElement.clientWidth;
  var height = videoElement.clientHeight;
  try {
    adsManager.init(width, height, google.ima.ViewMode.NORMAL);
    adsManager.start();
  } catch (adError) {
    // Play the video without ads, if an error occurs
    console.log("AdsManager could not be started");
    videoElement.play();
  }
}

...

9. AdsManager をレスポンシブにする

動画プレーヤーのサイズに合わせて広告が動的にサイズ変更されるようにするには、画面のサイズまたは向きが変わった場合に、ウィンドウのサイズ変更イベントで adsManager.resize() を呼び出す必要があります。

ads.js
...

window.addEventListener('resize', function(event) {
  console.log("window resized");
  if(adsManager) {
    var width = videoElement.clientWidth;
    var height = videoElement.clientHeight;
    adsManager.resize(width, height, google.ima.ViewMode.NORMAL);
  }
});

...

10. AdsManager イベントをリッスンする

AdsManager は、処理が必要なイベントもいくつか発生させます。これらのイベントは、状態変化の追跡、コンテンツ動画の再生と一時停止のトリガー、エラーの登録に使用されます。

エラー処理

AdsLoader 用に作成されたエラーハンドラを AdsManager のエラーハンドラとして使用するには、同じコールバック関数を持つ新しいイベント ハンドラを追加します。

ads.js
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
}

...

再生イベントと一時停止イベントのトリガー

AdsManager は表示する広告を挿入する準備が整うと、CONTENT_PAUSE_REQUESTED イベントを呼び出します。このイベントは、基盤となる動画プレーヤーの一時停止をトリガーすることで処理します。同様に、広告が完了すると、AdsManagerCONTENT_RESUME_REQUESTED イベントが発生します。このイベントを処理するには、ベースとなるコンテンツ動画の再生を再開します。

ads.js
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
      onContentPauseRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      onContentResumeRequested);
}

...

function onContentPauseRequested() {
  videoElement.pause();
}

function onContentResumeRequested() {
  videoElement.play();
}

モバイル デバイスで「クリックして一時停止」をトリガーする

AdContainer が動画要素をオーバーレイするため、ユーザーは基盤となるプレーヤーを直接操作することはできません。これは、モバイル デバイスのユーザーが、動画プレーヤーをタップして再生を一時停止できるものとして混乱する可能性があります。この問題に対処するために、IMA SDK では、広告オーバーレイからの IMA で処理されないクリックをすべて AdContainer 要素に渡し、そこで処理できます。これは、モバイル以外のブラウザ上のリニア広告には適用されません。広告をクリックすると、クリックスルー リンクが開きます。

クリックによる一時停止を実装するには、AdContainer にクリック ハンドラを追加し、基になる動画で再生イベントまたは一時停止イベントをトリガーします。

ads.js
...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adContainer.addEventListener('click', adContainerClick);
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

...

function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoElement.paused) {
    videoElement.play();
  } else {
    videoElement.pause();
  }
}

...

ノンリニア広告の再生をトリガーする

AdsManager は、広告の再生準備が整うとコンテンツ動画を一時停止しますが、この動作は広告の表示中もコンテンツの再生を続けるノンリニア広告については考慮していません。ノンリニア広告をサポートするには、AdsManager をリッスンして LOADED イベントを発生させます。次に、広告がリニアかどうかを確認し、リニア広告でない場合は、動画要素での再生を再開します。

ads.js
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  adsManager.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
      onContentPauseRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      onContentResumeRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.LOADED,
      onAdLoaded);
}

...

function onAdLoaded(adEvent) {
  var ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoElement.play();
  }
}

これで完了です。これで、IMA SDK を使用して広告をリクエストし、表示できます。SDK のより高度な機能については、他のガイドや GitHub のサンプルをご覧ください。