フルサービス DAI を設定する

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

このガイドでは、IMA DAI SDK をシンプルな動画プレーヤー アプリに統合する方法について説明します。統合が完了したサンプルを確認する場合は、GitHub から BasicExample をダウンロードしてください。

注: Android 用の IMA DAI SDK は、HLS ストリームと DASH ストリームの両方をサポートしています。

このガイドでは、HLS ストリームを再生するように ExoPlayer と IMA DAI SDK を構成する方法について説明します。HLS ストリームと DASH ストリームの両方をサポートする動画プレーヤーの例については、高度な例をご覧ください。

IMA DAI を使用するには、アド マネージャー 360 アドバンス アカウントが必要です。アド マネージャー アカウントをお持ちの場合は、アカウント マネージャーに詳細をお問い合わせください。アド マネージャーへの登録については、アド マネージャー ヘルプセンターをご覧ください。

重要なポイント: ExoPlayer IMA 拡張機能を使用すると、Android で IMA DAI を効率的に使用できます。詳しくは、ExoPlayer IMA 拡張機能ガイドと GitHub の ExoPlayerExample をご覧ください。

注: 他のプラットフォームとの統合や IMA クライアントサイド SDK の使用については、 Interactive Media Ads SDK をご覧ください。

IMA DAI の概要

IMA DAI の実装には、このガイドで説明されているように、主に 4 つの SDK コンポーネントが関与します。

• StreamDisplayContainer: 動画再生要素の上に配置され、広告 UI 要素を格納するコンテナ オブジェクト。
• AdsLoader: ストリームをリクエストし、ストリーム リクエスト レスポンス オブジェクトによってトリガーされたイベントを処理するオブジェクト。インスタンス化する広告ローダは 1 つだけにしてください。この広告ローダは、アプリのライフサイクル全体で再利用できます。
• StreamRequest: ストリーム リクエストを定義するオブジェクト。ストリーム リクエストは、ビデオ オンデマンドまたはライブ ストリームのいずれかです。ライブ配信リクエストではアセットキーを指定し、VOD リクエストでは CMS ID と動画 ID を指定します。どちらのリクエスト タイプでも、指定したストリームにアクセスするために必要な API キーと、Google アド マネージャーの設定で指定された広告識別子を IMA SDK で処理するための Google アド マネージャー ネットワーク コードを、必要に応じて含めることができます。
• StreamManager: ダイナミック広告挿入ストリームと DAI バックエンドとのやり取りを処理するオブジェクト。ストリーム マネージャーは、トラッキング ping を処理し、ストリーム イベントと広告イベントをパブリッシャーに転送します。

前提条件

• Android Studio
• SDK 統合用のサンプル動画プレーヤー アプリ

サンプル動画プレーヤー アプリをダウンロードして実行する

このサンプルアプリには、HLS 動画を再生する動画プレーヤーが用意されています。これを、IMA DAI SDK の DAI 機能を統合するための出発点として使用します。

1. サンプル動画プレーヤー アプリをダウンロードして解凍します。

2. Android Studio を起動し、[Open an existing Android Studio project] を選択します。Android Studio がすでに実行されている場合は、[File] > [New] > [Import Project] を選択します。SampleVideoPlayer/build.gradle を選択します。

3. [Tools] > [Android] > [Sync Project with Gradle Files] を選択して、Gradle 同期を実行します。

4. [Run] > [Run 'app'] を使用して、プレーヤー アプリが Android デバイスまたは Android Virtual Device でコンパイルされ、実行されることを確認します。動画ストリームの読み込みに少し時間がかかるのは正常です。

ヒント: Android アプリの開発が初めての場合は、USB デバッグと仮想デバイスの使用に関するチュートリアルをご覧ください。新しいアプリを実行して表示を確認するには、この 2 つのいずれかを行う必要があります。

サンプル動画プレーヤーを確認する

サンプル動画プレーヤーには、IMA DAI SDK 統合コードがまだ含まれていません。サンプルアプリは、主に次の 2 つの部分で構成されています。

1. samplevideoplayer/SampleVideoPlayer.java: IMA DAI 統合のベースとなる ExoPlayer ベースの HLS プレーヤー。

2. videoplayerapp/MyActivity.java: このアクティビティは、動画プレーヤーを作成し、Context と media3.ui.PlayerView を渡します。

IMA DAI SDK をプレーヤー アプリに追加する

また、IMA DAI SDK への参照も含める必要があります。Android Studio で、app/build.gradle にあるアプリケーション レベルの build.gradle ファイルに以下を追加します。IMA SDK では、ライブラリの脱糖を有効にする必要があります。そのためには、coreLibraryDesugaringEnabled true を設定し、'com.android.tools:desugar_jdk_libs' を依存関係として build.gradle ファイルに追加します。詳細については、nio 仕様の脱糖で使用可能な Java 11+ API をご覧ください。

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.11.0"
    coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.5")
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:2.3.21"))
    implementation("androidx.appcompat:appcompat:1.8.0")
    implementation("androidx.media3:media3-ui:$media3_version")
    implementation("androidx.media3:media3-exoplayer:$media3_version")
    implementation("androidx.media3:media3-exoplayer-hls:$media3_version")
    implementation("androidx.media3:media3-exoplayer-dash:$media3_version")
    implementation("androidx.mediarouter:mediarouter:1.8.1")
    implementation("com.google.ads.interactivemedia.v3:interactivemedia:3.40.0")
}
build.gradle

キーポイント: この時点でアプリをコンパイルして実行できますが、広告をリクエストしてディスプレイ広告を表示するための UI 要素やコードはまだ追加されていません。

IMA DAI SDK を統合する

1. videoplayerapp パッケージ（app/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/ 内）に SampleAdsWrapper という新しいクラスを作成して、既存の SampleVideoPlayer をラップし、IMA DAI を実装するロジックを追加します。これを行うには、まず DAI ストリームのリクエストに使用する AdsLoader を作成する必要があります。

   このスニペットには、HLS と DASH、ライブ ストリームと VOD ストリームのサンプル パラメータが含まれています。再生するストリームを設定するには、CONTENT_TYPE 変数を更新します。

   package com.google.ads.interactivemedia.v3.samples.videoplayerapp;
   
   import android.annotation.SuppressLint;
   import android.content.Context;
   import android.view.ViewGroup;
   import android.webkit.WebView;
   import androidx.annotation.Nullable;
   import com.google.ads.interactivemedia.v3.api.AdErrorEvent;
   import com.google.ads.interactivemedia.v3.api.AdEvent;
   import com.google.ads.interactivemedia.v3.api.AdsLoader;
   import com.google.ads.interactivemedia.v3.api.AdsManagerLoadedEvent;
   import com.google.ads.interactivemedia.v3.api.CuePoint;
   import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
   import com.google.ads.interactivemedia.v3.api.StreamDisplayContainer;
   import com.google.ads.interactivemedia.v3.api.StreamManager;
   import com.google.ads.interactivemedia.v3.api.StreamRequest;
   import com.google.ads.interactivemedia.v3.api.StreamRequest.StreamFormat;
   import com.google.ads.interactivemedia.v3.api.player.VideoProgressUpdate;
   import com.google.ads.interactivemedia.v3.api.player.VideoStreamPlayer;
   import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;
   import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer.SampleVideoPlayerCallback;
   import java.util.ArrayList;
   import java.util.HashMap;
   import java.util.List;
   
   /** This class adds ad-serving support to Sample HlsVideoPlayer */
   @SuppressLint("UnsafeOptInUsageError")
   /* @SuppressLint is needed for new media3 APIs. */
   public class SampleAdsWrapper
       implements AdEvent.AdEventListener, AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener {
   
     // Live HLS stream asset key.
     private static final String TEST_HLS_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";
   
     // Live DASH stream asset key.
     private static final String TEST_DASH_ASSET_KEY = "PSzZMzAkSXCmlJOWDmRj8Q";
   
     // VOD HLS content source and video IDs.
     private static final String TEST_HLS_CONTENT_SOURCE_ID = "2548831";
     private static final String TEST_HLS_VIDEO_ID = "tears-of-steel";
   
     // VOD DASH content source and video IDs.
     private static final String TEST_DASH_CONTENT_SOURCE_ID = "2559737";
     private static final String TEST_DASH_VIDEO_ID = "tos-dash";
   
     private static final String NETWORK_CODE = "21775744923";
   
     private static final String PLAYER_TYPE = "DAISamplePlayer";
   
     private enum ContentType {
       LIVE_HLS,
       LIVE_DASH,
       VOD_HLS,
       VOD_DASH,
     }
   
     // Set CONTENT_TYPE to the associated enum for the stream type you would like to test.
     private static final ContentType CONTENT_TYPE = ContentType.VOD_HLS;
   
     /** Log interface, so we can output the log commands to the UI or similar. */
     public interface Logger {
       void log(String logMessage);
     }
   
     private final ImaSdkFactory sdkFactory;
     private AdsLoader adsLoader;
     private StreamManager streamManager;
     private final List<VideoStreamPlayer.VideoStreamPlayerCallback> playerCallbacks;
   
     private final SampleVideoPlayer videoPlayer;
     private final Context context;
     private final ViewGroup adUiContainer;
   
     private String fallbackUrl;
     private Logger logger;
   
     /**
      * Creates a new SampleAdsWrapper that implements IMA direct-ad-insertion.
      *
      * @param context the app's context.
      * @param videoPlayer underlying HLS video player.
      * @param adUiContainer ViewGroup in which to display the ad's UI.
      */
     public SampleAdsWrapper(Context context, SampleVideoPlayer videoPlayer, ViewGroup adUiContainer) {
       this.videoPlayer = videoPlayer;
       this.context = context;
       this.adUiContainer = adUiContainer;
       sdkFactory = ImaSdkFactory.getInstance();
       playerCallbacks = new ArrayList<>();
       createAdsLoader();
     }
   
     private void enableWebViewDebugging() {
       WebView.setWebContentsDebuggingEnabled(true);
     }
   
     private void createAdsLoader() {
       enableWebViewDebugging();
       VideoStreamPlayer videoStreamPlayer = createVideoStreamPlayer();
       StreamDisplayContainer displayContainer =
           ImaSdkFactory.createStreamDisplayContainer(adUiContainer, videoStreamPlayer);
       videoPlayer.setSampleVideoPlayerCallback(createSampleVideoPlayerCallback());
       adsLoader =
           sdkFactory.createAdsLoader(context, MyActivity.getImaSdkSettings(), displayContainer);
     }
   
     public void requestAndPlayAds() {
       adsLoader.addAdErrorListener(this);
       adsLoader.addAdsLoadedListener(this);
       adsLoader.requestStream(buildStreamRequest());
     }
   SampleAdsWrapper.java

2. VideoStreamPlayer.VideoStreamPlayerCallback を拡張する SampleVideoPlayerCallback インターフェース インスタンスの作成を処理する createSampleVideoPlayerCallback() ヘルパー メソッドを作成します。

   DAI を使用するには、プレーヤーが ID3 イベントを IMA DAI SDK に渡す必要があります。次のサンプルコードでは、callback.onUserTextReceived() メソッドがこれを行います。

   private SampleVideoPlayerCallback createSampleVideoPlayerCallback() {
     return new SampleVideoPlayerCallback() {
       @Override
       public void onUserTextReceived(String userText) {
         for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
           callback.onUserTextReceived(userText);
         }
       }
   
       @Override
       public void onSeek(int windowIndex, long positionMs) {
         // See if we would seek past an ad, and if so, jump back to it.
         long newSeekPositionMs = positionMs;
         if (streamManager != null) {
           CuePoint prevCuePoint = streamManager.getPreviousCuePointForStreamTimeMs(positionMs);
           if (prevCuePoint != null && !prevCuePoint.isPlayed()) {
             newSeekPositionMs = prevCuePoint.getStartTimeMs();
           }
         }
         videoPlayer.seekTo(windowIndex, newSeekPositionMs);
       }
   
       @Override
       public void onContentComplete() {
         for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
           callback.onContentComplete();
         }
       }
   
       @Override
       public void onPause() {
         for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
           callback.onPause();
         }
       }
   
       @Override
       public void onResume() {
         for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
           callback.onResume();
         }
       }
   
       @Override
       public void onVolumeChanged(int percentage) {
         for (VideoStreamPlayer.VideoStreamPlayerCallback callback : playerCallbacks) {
           callback.onVolumeChanged(percentage);
         }
       }
     };
   }
   SampleAdsWrapper.java

3. SteamRequest を作成するために、buildStreamRequest() メソッドを追加します。このメソッドは、CONTENT_TYPE 変数の設定方法に基づいて、異なるストリームを切り替えます。このガイドで使用するデフォルトのストリームは、IMA のサンプル VOD HLS ストリームです。

   @Nullable
   private StreamRequest buildStreamRequest() {
     StreamRequest request;
     switch (CONTENT_TYPE) {
       case LIVE_HLS:
         // Live HLS stream request.
         return sdkFactory.createLiveStreamRequest(TEST_HLS_ASSET_KEY, null, NETWORK_CODE);
       case LIVE_DASH:
         // Live DASH stream request.
         return sdkFactory.createLiveStreamRequest(TEST_DASH_ASSET_KEY, null, NETWORK_CODE);
       case VOD_HLS:
         // VOD HLS request.
         request =
             sdkFactory.createVodStreamRequest(
                 TEST_HLS_CONTENT_SOURCE_ID, TEST_HLS_VIDEO_ID, null, NETWORK_CODE);
         request.setFormat(StreamFormat.HLS);
         return request;
       case VOD_DASH:
         // VOD DASH request.
         request =
             sdkFactory.createVodStreamRequest(
                 TEST_DASH_CONTENT_SOURCE_ID, TEST_DASH_VIDEO_ID, null, NETWORK_CODE);
         request.setFormat(StreamFormat.DASH);
         return request;
     }
     // Content type not selected.
     return null;
   }
   SampleAdsWrapper.java

4. また、ストリームを再生するには VideoStreamPlayer が必要です。そのため、VideoStreamPlayer を実装する匿名クラスを作成する createVideoStreamPlayer() メソッドを追加します。

   private VideoStreamPlayer createVideoStreamPlayer() {
     return new VideoStreamPlayer() {
       @Override
       public void loadUrl(String url, List<HashMap<String, String>> subtitles) {
         videoPlayer.setStreamUrl(url);
         videoPlayer.play();
       }
   
       @Override
       public void pause() {
         // Pause player.
         videoPlayer.pause();
       }
   
       @Override
       public void resume() {
         // Resume player.
         videoPlayer.play();
       }
   
       @Override
       public int getVolume() {
         // Make the video player play at the current device volume.
         return 100;
       }
   
       @Override
       public void addCallback(VideoStreamPlayerCallback videoStreamPlayerCallback) {
         playerCallbacks.add(videoStreamPlayerCallback);
       }
   
       @Override
       public void removeCallback(VideoStreamPlayerCallback videoStreamPlayerCallback) {
         playerCallbacks.remove(videoStreamPlayerCallback);
       }
   
       @Override
       public void onAdBreakStarted() {
         // Disable player controls.
         videoPlayer.enableControls(false);
         log("Ad Break Started\n");
       }
   
       @Override
       public void onAdBreakEnded() {
         // Re-enable player controls.
         if (videoPlayer != null) {
           videoPlayer.enableControls(true);
         }
         log("Ad Break Ended\n");
       }
   
       @Override
       public void onAdPeriodStarted() {
         log("Ad Period Started\n");
       }
   
       @Override
       public void onAdPeriodEnded() {
         log("Ad Period Ended\n");
       }
   
       @Override
       public void seek(long timeMs) {
         // An ad was skipped. Skip to the content time.
         videoPlayer.seekTo(timeMs);
         log("seek");
       }
   
       @Override
       public VideoProgressUpdate getContentProgress() {
         return new VideoProgressUpdate(
             videoPlayer.getCurrentPositionMs(), videoPlayer.getDuration());
       }
     };
   }
   SampleAdsWrapper.java

5. 必要なリスナーを実装し、エラー処理のサポートを追加します。

   AdErrorListener の実装に注意してください。広告の再生に失敗すると、代替 URL が呼び出されます。コンテンツと広告が 1 つのストリームに含まれているため、DAI ストリームでエラーが発生した場合にフォールバック ストリームを呼び出せるようにしておく必要があります。

   /** AdErrorListener implementation */
   @Override
   public void onAdError(AdErrorEvent event) {
     log(String.format("Error: %s\n", event.getError().getMessage()));
     // play fallback URL.
     log("Playing fallback Url\n");
     videoPlayer.setStreamUrl(fallbackUrl);
     videoPlayer.enableControls(true);
     videoPlayer.play();
   }
   
   /** AdEventListener implementation */
   @Override
   public void onAdEvent(AdEvent event) {
     switch (event.getType()) {
       case AD_PROGRESS:
         // Do nothing or else log will be filled by these messages.
         break;
       default:
         log(String.format("Event: %s\n", event.getType()));
         break;
     }
   }
   
   /** AdsLoadedListener implementation */
   @Override
   public void onAdsManagerLoaded(AdsManagerLoadedEvent event) {
     streamManager = event.getStreamManager();
     streamManager.addAdErrorListener(this);
     streamManager.addAdEventListener(this);
     streamManager.init();
   }
   
   /** Sets fallback URL in case ads stream fails. */
   void setFallbackUrl(String url) {
     fallbackUrl = url;
   }
   SampleAdsWrapper.java

6. ロギング用のコードを追加します。

   /** Sets logger for displaying events to screen. Optional. */
   void setLogger(Logger logger) {
     this.logger = logger;
   }
   
   private void log(String message) {
     if (logger != null) {
       logger.log(message);
     }
   }
   SampleAdsWrapper.java

7. videoplayerapp の MyActivity を変更して、SampleAdsWrapper をインスタンス化して呼び出します。また、ヘルパー メソッドを使用して ImaSdkFactory.initialize() を呼び出し、ImaSdkSettings インスタンスを作成します。

   重要: IMA の読み込み時間を短縮するには、アプリのライフサイクルのなるべく早い段階で ImaSdkFactory.initialize() メソッドを呼び出します。このメソッドを早期に呼び出すことで、最初のストリーム リクエストの前に IMA が必要なリソースを読み込む時間を最大化できます。ImaSdkFactory.initialize() メソッド呼び出しは ImaSdkSettings インスタンスを受け入れます。ここで使用する設定値と、AdsLoader インスタンスの作成時に使用する設定値が同じであることを確認してください。この例では、getImaSdkSettings() ヘルパー メソッドを使用して、設定値が同じであることを確認しています。詳細については、IMA の読み込み時間を最適化するガイドをご覧ください。
   package com.google.ads.interactivemedia.v3.samples.videoplayerapp;
   
   import android.annotation.SuppressLint;
   import android.app.Activity;
   import android.content.res.Configuration;
   import android.os.Bundle;
   import android.util.Log;
   import android.view.View;
   import android.widget.ImageButton;
   import android.widget.ScrollView;
   import android.widget.TextView;
   import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
   import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
   import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;
   
   /** Main Activity that plays media using {@link SampleVideoPlayer}. */
   @SuppressLint("UnsafeOptInUsageError")
   /* @SuppressLint is needed for new media3 APIs. */
   public class MyActivity extends Activity {
   
     private static final String DEFAULT_STREAM_URL =
         "https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8";
     private static final String APP_LOG_TAG = "ImaDaiExample";
     private static final String PLAYER_TYPE = "DAISamplePlayer";
     private static ImaSdkSettings imaSdkSettings;
   
     protected SampleVideoPlayer sampleVideoPlayer;
     protected ImageButton playButton;
   
     private boolean contentHasStarted = false;
   
     @Override
     protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_my);
   
       // Initialize the IMA SDK as early as possible when the app starts. If your app already
       // overrides Application.onCreate(), call this method inside the onCreate() method.
       // https://developer.android.com/topic/performance/vitals/launch-time#app-creation
       ImaSdkFactory.getInstance().initialize(this, getImaSdkSettings());
   
       View rootView = findViewById(R.id.videoLayout);
       sampleVideoPlayer =
           new SampleVideoPlayer(rootView.getContext(), rootView.findViewById(R.id.playerView));
       sampleVideoPlayer.enableControls(false);
       playButton = rootView.findViewById(R.id.playButton);
       final SampleAdsWrapper sampleAdsWrapper =
           new SampleAdsWrapper(this, sampleVideoPlayer, rootView.findViewById(R.id.adUiContainer));
       sampleAdsWrapper.setFallbackUrl(DEFAULT_STREAM_URL);
   
       final ScrollView scrollView = findViewById(R.id.logScroll);
       final TextView textView = findViewById(R.id.logText);
   
       sampleAdsWrapper.setLogger(
           logMessage -> {
             Log.i(APP_LOG_TAG, logMessage);
             if (textView != null) {
               textView.append(logMessage);
             }
             if (scrollView != null) {
               scrollView.post(() -> scrollView.fullScroll(View.FOCUS_DOWN));
             }
           });
   
       // Set up play button listener to play video then hide play button.
       playButton.setOnClickListener(
           view -> {
             if (contentHasStarted) {
               sampleVideoPlayer.play();
             } else {
               contentHasStarted = true;
               sampleVideoPlayer.enableControls(true);
               sampleAdsWrapper.requestAndPlayAds();
             }
             playButton.setVisibility(View.GONE);
           });
       orientVideoDescription(getResources().getConfiguration().orientation);
     }
   MyActivity.java

8. ImaSdkSettings インスタンスを作成する getImaSdkSettings() ヘルパー メソッドを追加します。

   public static ImaSdkSettings getImaSdkSettings() {
     if (imaSdkSettings == null) {
       imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings();
       imaSdkSettings.setPlayerType(PLAYER_TYPE);
       // Set any additional IMA SDK settings here.
     }
     return imaSdkSettings;
   }
   MyActivity.java

9. アクティビティのレイアウト ファイル activity_my.xml を変更して、ロギング用の UI 要素を追加します。

   <!-- UI element for viewing SDK event log -->
   <ScrollView
       android:id="@+id/logScroll"
       android:layout_width="match_parent"
       android:layout_height="0dp"
       android:layout_weight="0.5"
       android:padding="5dp"
       android:background="#DDDDDD">
   
       <TextView
           android:id="@+id/logText"
           android:layout_width="match_parent"
           android:layout_height="wrap_content">
       </TextView>
   </ScrollView>
   activity_my.xml

おめでとうございます。これで、Android アプリで動画広告をリクエストして表示できるようになりました。実装を微調整するには、ブックマーク、スナップバック、API ドキュメントをご覧ください。

トラブルシューティング

動画広告の再生で問題が発生した場合は、完成した BasicExample をダウンロードしてみてください。BasicExample で正常に動作する場合は、アプリの IMA 統合コードに問題がある可能性があります。

それでも問題が解決しない場合は、IMA SDK フォーラムをご覧ください。