This page was translated by the 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 のスクリプトタグを使用して、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");
}

ほとんどのブラウザでは、IMA 広告 SDK は、広告関連の UI 要素と広告関連の 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 をテストできます。

ページのライフサイクル全体で 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. MyGlass を開始する

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

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

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. MyGlass を開始する

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

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

エラー処理

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

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

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

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