サービスに関するご意見やご提案は、Google 広告と測定のコミュニティサーバーの公式アドマネージャー Discord チャンネルにご参加ください。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

IMA SDK を設定する

プラットフォームを選択: HTML5 Android iOS tvOS

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

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

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

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

AdDisplayContainer: IMA が広告 UI 要素をレンダリングし、視認性を測定する場所を指定するコンテナオブジェクト。アクティブビューや Open Measurement などがあります。
AdsLoader: 広告をリクエストし、広告リクエストレスポンスからのイベントを処理するオブジェクト。広告ローダは 1 つだけインスタンス化し、アプリケーションのライフサイクル全体で再利用する必要があります。
AdsRequest: 広告リクエストを定義するオブジェクト。広告リクエストでは、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 動画要素と、再生をトリガーするボタンを作成します。次の例では、IMA SDK をインポートし、 AdDisplayContainer コンテナ要素を設定しています。詳細については、 IMA SDK をインポートする手順と広告コンテナを作成する手順をそれぞれご覧ください。

<html>
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <link rel="stylesheet" href="style.css">
  </head>

  <body>
    <div id="mainContainer">
      <div id="content">
        <video id="contentElement">
          <source src="https://storage.googleapis.com/gvabox/media/samples/stock.mp4"></source>
        </video>
      </div>
      <div id="adContainer"></div>
    </div>
    <button id="playButton">Play</button>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>
index.html

#mainContainer {
  position: relative;
  width: 640px;
  height: 360px;
}

#content {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}

#contentElement {
  width: 640px;
  height: 360px;
  overflow: hidden;
}

#playButton {
  margin-top:10px;
  vertical-align: top;
  width: 350px;
  height: 60px;
  padding: 0;
  font-size: 22px;
  color: white;
  text-align: center;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
  background: #2c3e50;
  border: 0;
  border-bottom: 2px solid #22303f;
  cursor: pointer;
  -webkit-box-shadow: inset 0 -2px #22303f;
  box-shadow: inset 0 -2px #22303f;
}style.css

let adsManager;
let adsLoader;
let adDisplayContainer;
let isAdPlaying;
let isContentFinished;
let playButton;
let videoContent;
let adContainer;

// On window load, attach an event to the play button click
// that triggers playback of the video element.
window.addEventListener('load', function(event) {
  videoContent = document.getElementById('contentElement');
  adContainer = document.getElementById('adContainer');
  adContainer.addEventListener('click', adContainerClick);
  playButton = document.getElementById('playButton');
  playButton.addEventListener('click', playAds);
  setUpIMA();
});ads.js

style.css ファイルと ads.js ファイルを読み込むために必要なタグを追加します。次に、 styles.css を変更して、動画プレーヤーがモバイルデバイスに対応するようにします。最後に、 ads.js で変数を宣言し、再生ボタンをクリックしたときに動画再生をトリガーします。

ads.js コードスニペットには、広告ローダを初期化して広告リクエストを行うセクションで定義されている setUpIMA() の呼び出しが含まれています。

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

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

注: 詳細なコンソールログを受け取るには、ima3.js を ima3_debug.js に置き換えます。ただし、ima3_debug.js は本番環境のアプリでは使用しないでください。

<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>index.html

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

この広告コンテナ要素を実装するには、まず div を video-container 要素内に作成します。次に、CSS を更新して、要素を左上隅に配置しますvideo-element。最後に、createAdDisplayContainer() 関数を追加して、 AdDisplayContainer オブジェクトを新しい広告コンテナ div を使用して作成します。

<div id="adContainer"></div>index.html

#adContainer {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}style.css

/**
 * Sets the 'adContainer' div as the IMA ad display container.
 */
function createAdDisplayContainer() {
  adDisplayContainer = new google.ima.AdDisplayContainer(
      document.getElementById('adContainer'), videoContent);
}ads.js

5. 広告ローダを初期化して広告リクエストを行う

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

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

AdsLoader.addEventListener を使用して、読み込まれた広告とエラーイベントをリッスンして対応します。次のイベントをリッスンします。

ADS_MANAGER_LOADED
AD_ERROR

onAdsManagerLoaded() リスナーと onAdError() リスナーを作成するには、次の例をご覧ください。

/**
 * Sets up IMA ad display container, ads loader, and makes an ad request.
 */
function setUpIMA() {
  // Create the ad display container.
  createAdDisplayContainer();
  // Create ads loader.
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  // Listen and respond to ads loaded and error events.
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded, false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError, false);

  // An event listener to tell the SDK that our content video
  // is completed so the SDK can play any post-roll ads.
  const contentEndedListener = function() {
    // An ad might have been playing in the content element, in which case the
    // content has not actually ended.
    if (isAdPlaying) return;
    isContentFinished = true;
    adsLoader.contentComplete();
  };
  videoContent.onended = contentEndedListener;

  // Request video ads.
  const 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&correlator=';

  // Specify the linear and nonlinear slot sizes. This helps the SDK to
  // select the correct creative if multiple are returned.
  adsRequest.linearAdSlotWidth = 640;
  adsRequest.linearAdSlotHeight = 400;

  adsRequest.nonLinearAdSlotWidth = 640;
  adsRequest.nonLinearAdSlotHeight = 150;

  adsLoader.requestAds(adsRequest);
}ads.js

6. AdsLoader イベントに対応する

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

読み込みプロセス中に発生したエラーを処理してください。広告が読み込まれない場合は、ユーザーがコンテンツを視聴するのを妨げないように、広告なしでメディア再生が続行されるようにしてください。

/**
 * Handles the ad manager loading and sets ad event listeners.
 * @param {!google.ima.AdsManagerLoadedEvent} adsManagerLoadedEvent
 */
function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Get the ads manager.
  const adsRenderingSettings = new google.ima.AdsRenderingSettings();
  adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
  // videoContent should be set to the content video element.
  adsManager =
      adsManagerLoadedEvent.getAdsManager(videoContent, adsRenderingSettings);

  // Add listeners to the required events.
  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);
}

/**
 * Handles ad errors.
 * @param {!google.ima.AdErrorEvent} adErrorEvent
 */
function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  adsManager.destroy();
}ads.js

onAdsManagerLoaded() 関数で設定されたリスナーの詳細については、次のサブセクションをご覧ください。

`AdsManager` エラーを処理する

AdsLoader 用に作成されたエラーハンドラは、AdsManager 用のエラーハンドラとしても機能します。onAdError() 関数を再利用するイベントハンドラをご覧ください。

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

再生イベントと一時停止イベントを処理する

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

adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
    onContentResumeRequested);ads.js

onContentPauseRequested() および onContentResumeRequested() 関数の定義については、次の例をご覧ください。

/**
 * Pauses video content and sets up ad UI.
 */
function onContentPauseRequested() {
  isAdPlaying = true;
  videoContent.pause();
  // This function is where you should setup UI for showing ads (for example,
  // display ad timer countdown, disable seeking and more.)
  // setupUIForAds();
}

/**
 * Resumes video content and removes ad UI.
 */
function onContentResumeRequested() {
  isAdPlaying = false;
  if (!isContentFinished) {
    videoContent.play();
  }
  // This function is where you should ensure that your UI is ready
  // to play content. It is the responsibility of the Publisher to
  // implement this function when necessary.
  // setupUIForContent();
}ads.js

ノンリニア広告の再生中にコンテンツ再生を処理する

AdsManager は、広告を再生する準備ができるとコンテンツ動画を一時停止しますが、この動作は、広告が表示されている間もコンテンツの再生が続くノンリニア広告には対応していません。

adsManager.addEventListener(google.ima.AdEvent.Type.LOADED, onAdLoaded);ads.js

ノンリニア広告をサポートするには、AdsManager が LOADED イベントを発生させるのをリッスンします。広告がリニアかどうかを確認し、リニアでない場合は動画要素の再生を再開します。

onAdLoaded() 関数の定義については、次の例をご覧ください。

/**
 * Handles ad loaded event to support non-linear ads. Continues content playback
 * if the ad is not linear.
 * @param {!google.ima.AdEvent} adEvent
 */
function onAdLoaded(adEvent) {
  let ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoContent.play();
  }
}ads.js

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

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

クリックして一時停止を実装するには、ウィンドウの読み込みリスナーで呼び出される adContainerClick() クリックハンドラ関数を追加します。

/**
 * Handles clicks on the ad container to support expected play and pause
 * behavior on mobile devices.
 * @param {!Event} event
 */
function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoContent.paused) {
    videoContent.play();
  } else {
    videoContent.pause();
  }
}ads.js

8. AdsManager を開始する

広告再生を開始するには、AdsManager を初期化して開始します。モバイルブラウザを完全にサポートするには、広告を自動的に再生できないため、再生ボタンをクリックするなど、ページに対するユーザー操作から広告再生をトリガーします。

/**
 * Loads the video content and initializes IMA ad playback.
 */
function playAds() {
  // Initialize the container. Must be done through a user action on mobile
  // devices.
  videoContent.load();
  adDisplayContainer.initialize();

  try {
    // Initialize the ads manager. This call starts ad playback for VMAP ads.
    adsManager.init(640, 360);
    // Call play to start showing the ad. Single video and overlay ads will
    // start at this time; the call will be ignored for VMAP ads.
    adsManager.start();
  } catch (adError) {
    // An error may be thrown if there was a problem with the VAST response.
    videoContent.play();
  }
}ads.js

9. プレーヤーのサイズ変更をサポートする

広告のサイズを動的に変更して動画プレーヤーのサイズに合わせたり、画面の向きの変更に合わせたりするには、ウィンドウのサイズ変更イベントに応じてadsManager.resize() を呼び出します。

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

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