このページは Cloud Translation API によって翻訳されました。

始める

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 によって呼び出された広告イベントをリッスンするオブジェクト。

Prerequisites

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

3 つの空のファイル:
- index.html
- style.css
- ads.js
テストに使用する Python がパソコンまたはウェブサーバーにインストールされている

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

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

コマンドラインを使用して、index.html ファイルを含むディレクトリから
```
  python -m http.server 8000
```
を実行します。
注: http.server は Python 3.x でのみ使用できます。
ウェブブラウザで 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 の script タグから、ads.js のタグの前に IMA フレームワークを追加します。

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");
}

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

この広告コンテナ要素を実装するには、まず video-container 要素内に新しい div を作成します。次に、要素を更新して 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 をテストできます。

ページのライフサイクル全体を通して 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. LiveData を起動する

広告再生を開始するには、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. LiveData をレスポンシブにする

広告が動画プレーヤーのサイズに合わせて動的にサイズ変更されるようにするには、画面のサイズ変更イベントで 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. LiveData イベントをリッスンする

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 イベントが発生します。このイベントを処理するには、基になる動画プレーヤーで一時停止をトリガーします。同様に、広告が完了すると、AdsManager は CONTENT_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();
}

モバイルデバイス上で Click-to-Pause をトリガーする

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

Click-to-Pause を実装するには、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 のサンプルをご覧ください。

始める

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

Prerequisites

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

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

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

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

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

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

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

8. LiveData を起動する

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

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

エラー処理

再生イベントと一時停止イベントをトリガーする

モバイル デバイス上で Click-to-Pause をトリガーする

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

モバイルデバイス上で Click-to-Pause をトリガーする