このページは 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: IMA が広告 UI 要素をレンダリングする場所を指定し、アクティブビューやオープン測定などの視認性を測定するコンテナオブジェクト。
AdsLoader: 広告をリクエストし、広告リクエストレスポンスからのイベントを処理するオブジェクト。インスタンス化すべき広告ローダは 1 つだけです。この広告ローダは、アプリのライフサイクル全体で再利用できます。
AdsRequest: 広告リクエストを定義するオブジェクト。Google 広告リクエストでは、VAST 広告タグの URL と、広告のサイズなどの追加パラメータを指定します。
AdsManager: 広告リクエストへのレスポンスを含むオブジェクト。広告の再生を制御し、SDK によって発生した広告イベントをリッスンします。

前提条件

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

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 で、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 を作成します。次に、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 秒間のプレロール広告が含まれています。この広告タグ URL や他の広告タグ URL は、IMA Video Suite Inspector を使用してテストできます。

ベストプラクティスとして、ページのライフサイクル全体で 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 イベントを発生させます。このイベントを処理するには、基盤となる動画プレーヤーで一時停止をトリガーします。同様に、広告が完了すると、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();
}

モバイルデバイスでのクリックして一時停止のトリガー

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 のサンプルをご覧ください。

始める

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

前提条件

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

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

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

4. ページと動画プレーヤーのハンドラを接続する

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

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

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

8. AdsManager を起動する

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

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

エラー処理

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

モバイル デバイスでのクリックして一時停止のトリガー

ノンリニア広告での再生のトリガー

モバイルデバイスでのクリックして一時停止のトリガー