設定全方位服務 DAI

選取平台： HTML5 Android iOS tvOS Cast Roku

本指南說明如何將 IMA DAI SDK 整合至簡易的影片播放器應用程式。如要查看或按照完整的整合範例操作，請從 GitHub 下載 BasicExample。

注意： Android 版 IMA DAI SDK 支援 HLS 和 DASH 串流。

本指南說明如何設定 ExoPlayer 和 IMA DAI SDK，以便播放 HLS 串流。如需同時支援 HLS 和 DASH 串流的影片播放器範例，請參閱進階範例。

如要使用 IMA DAI，您必須擁有 Ad Manager 360 Advanced 帳戶。如果您有 Ad Manager 帳戶，請與客戶經理聯絡，瞭解詳情。如要瞭解如何申請 Ad Manager，請前往 Ad Manager 說明中心。

重點： ExoPlayer IMA 擴充功能提供簡便的方法，可在 Android 上使用 IMA DAI。詳情請參閱 ExoPlayer IMA 擴充功能指南和 GitHub 上的 ExoPlayerExample。

注意：如要瞭解如何與其他平台整合，或使用 IMA 用戶端 SDK，請參閱 互動式媒體廣告 SDK。

IMA DAI 總覽

如要導入 IMA DAI，需要使用四個主要的 SDK 元件，如本指南所示：

• StreamDisplayContainer： 位於影片播放元素上方的容器物件，用於容納廣告 UI 元素。
• AdsLoader： 這個物件會要求串流，並處理串流要求回應物件觸發的事件。 您只需要例項化一個廣告載入器，即可在應用程式的整個生命週期中重複使用。
• StreamRequest：定義串流要求的物件。串流請求可以是隨選影片或直播。直播請求會指定素材資源金鑰，VOD 請求則會指定 CMS ID 和影片 ID。這兩種要求類型都可以選擇加入 API 金鑰 (用於存取指定串流)，以及 Google Ad Manager 聯播網代碼 (用於讓 IMA SDK 按照 Google Ad Manager 設定處理廣告 ID)。
• 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 虛擬裝置上編譯及執行。影片串流通常需要一些時間載入，才能開始播放。

提示： 如果您是 Android 應用程式開發新手，請參閱 USB 偵錯和使用虛擬裝置的教學課程。 您必須完成其中一項操作，才能執行新應用程式並查看外觀。

查看範例影片播放器

範例影片播放器尚未包含任何 IMA DAI SDK 整合程式碼。範例應用程式包含兩個主要部分：

1. samplevideoplayer/SampleVideoPlayer.java：以 ExoPlayer 為基礎的 HLS 播放器，是 IMA DAI 整合的基礎。

2. videoplayerapp/MyActivity.java：這項活動會建立影片播放器，並將 Context 和 media3.ui.PlayerView 傳遞給播放器。

在播放器應用程式中加入 IMA DAI SDK

此外，您也必須加入 IMA DAI SDK 的參照。在 Android Studio 中，將下列內容新增至應用程式層級的 build.gradle 檔案 (位於 app/build.gradle)。IMA SDK 必須啟用程式庫脫糖功能，因此您必須在 build.gradle 檔案中設定 coreLibraryDesugaringEnabled true，並新增 'com.android.tools:desugar_jdk_libs' 做為依附元件。詳情請參閱「使用 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 的邏輯。為此，您必須先建立 AdsLoader，用於要求 DAI 串流。

   這個程式碼片段包含 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. 建立 createSampleVideoPlayerCallback() 輔助方法，用於建立擴充 VideoStreamPlayer.VideoStreamPlayerCallback 的 SampleVideoPlayerCallback 介面例項。

   如要與 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. 新增 buildStreamRequest() 方法，建立 SteamRequest。這個方法會根據您設定 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 才能播放串流，因此請新增 createVideoStreamPlayer() 方法，建立實作 VideoStreamPlayer 的匿名類別。

   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 實作，因為如果廣告無法播放，系統會呼叫備用網址。由於內容和廣告都在同一個串流中，因此您必須做好準備，在 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. 新增 getImaSdkSettings() 輔助方法，建立 ImaSdkSettings 執行個體。

   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 的版面配置檔案 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 論壇。