设置全方位服务 DAI

本指南演示了如何将 IMA DAI SDK 集成到简单的视频播放器应用中。如果您想查看或按照完整的集成示例进行操作，请从 GitHub 下载 BasicExample。

IMA DAI 概览

如本指南所示，实现 IMA DAI 涉及四个主要 SDK 组件：

• StreamDisplayContainer：一个容器对象，位于视频播放元素之上，用于容纳广告界面元素。
• AdsLoader：一个对象，用于请求视频流并处理由视频流请求响应对象触发的事件。 您应该只实例化一个广告加载器，该加载器可在应用的整个生命周期内重复使用。
• StreamRequest：定义流请求的对象。视频流请求可以针对视频点播或直播。直播请求会指定素材资源键，而 VOD 请求会指定 CMS ID 和视频 ID。这两种请求类型都可以选择包含访问指定视频流所需的 API 密钥，以及供 IMA SDK 按照 Google Ad Manager 设置中的指定方式处理广告标识符的 Google Ad Manager 广告资源网代码。
• 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. 依次选择工具 > Android > 将项目与 Gradle 文件同步，运行 Gradle 同步。

4. 依次选择 Run > Run 'app'，确保播放器应用可在实体 Android 设备或 Android 虚拟设备上编译和运行。视频流在播放前需要一些时间加载，这是正常现象。

检查示例视频播放器

示例视频播放器尚未包含任何 IMA DAI SDK 集成代码。 示例应用包含两个主要部分：

1. samplevideoplayer/SampleVideoPlayer.java：一个基于 ExoPlayer 的 HLS 播放器，用作 IMA DAI 集成的基础。

2. videoplayerapp/MyActivity.java：此 activity 会创建视频播放器，并向其传递 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

集成 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 实例。

   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 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 论坛。