開始する

IMA SDK を使用すると、ウェブサイトやアプリにマルチメディア広告を簡単に統合できます。IMA SDK は 任意のネットワークから広告をリクエストし、 <ph type="x-smartling-placeholder"></ph> VAST 準拠の広告サーバーを実装し、アプリでの広告再生を管理できます。IMA クライアントサイド SDK では 広告の再生は SDK で処理され、コンテンツ動画の再生は制御できる。広告は アプリのコンテンツ動画プレーヤーの上に別の動画プレーヤーを配置します。

このガイドでは、シンプルな動画プレーヤー アプリに IMA SDK を統合する方法について説明します。もし 完成したサンプル統合を表示または参照できます。 簡単な例をご覧ください。もし SDK が統合済みの HTML5 プレーヤーに興味がある場合は、 Video.js 用 IMA SDK プラグイン

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

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

  • AdDisplayContainer: 広告がレンダリングされるコンテナ オブジェクト。
  • AdsLoader: 広告をリクエストし、広告リクエスト レスポンスからのイベントを処理するオブジェクト。必要なのは 1 つの広告ローダをインスタンス化して、アプリのライフサイクルを通じて再利用できるようにします。
  • AdsRequest: 広告リクエストを定義するオブジェクト。広告リクエストでは、VAST 広告タグの URL と 追加パラメータを使用できます
  • AdsManager: 広告リクエストへのレスポンスを含むオブジェクト。広告の再生の制御を行い、 イベントを記録します。

前提条件

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

  • 3 つの空のファイル: <ph type="x-smartling-placeholder">
      </ph>
    • 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.htmlads.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 を更新します。 モバイル デバイスでページをレスポンシブにするためのサイズ調整
で確認できます。 <ph type="x-smartling-placeholder">で確認できます。 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 オブジェクトなので、これらの値を手動で設定する必要はありません。

<ph type="x-smartling-placeholder">

この広告コンテナ要素を実装するには、まず新しい divvideo-container 要素。次に、要素が左上に配置されるように CSS を更新します。 video-element の隅まで移動できます。最後に、Terraform 内でコンテナの変数を ページの読み込み時に実行される 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.AdsLoaderADS_MANAGER_LOADED イベント。コールバックに渡されたイベントを解析して、 AdsManager オブジェクト。AdsManager は、広告に対するレスポンスで定義された個別の広告を読み込みます。 できます。

また、読み込みプロセス中に発生する可能性のあるエラーに必ず対処してください。広告が 読み込みの際には、メディアの再生を広告なしで続行し、 向上させることができます

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 用に作成されたエラーハンドラは、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 を使用して広告をリクエストし、表示できるようになりました。詳細情報 高度な機能については、他のガイドや GitHub のサンプルをご覧ください。