如需讨论我们的产品并提供反馈，请加入 Google 广告和效果衡量社区服务器中的官方 Ad Manager Discord 频道。

此页面由 Cloud Translation API 翻译。

设置 IMA SDK for DAI

借助 IMA SDK，您可以轻松地将多媒体广告集成到网站和应用中。IMA SDK 可以从任何符合 VAST 标准的广告服务器请求广告，并在您的应用中管理广告播放。借助 IMA DAI SDK，应用可以针对广告和内容视频（VOD 或直播内容）发出视频流请求。然后，SDK 会返回一个组合视频流，这样您就不必在应用内管理广告和内容视频之间的切换。

选择您感兴趣的 DAI 解决方案

全方位服务 DAI

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

IMA DAI 概览

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

StreamDisplayContainer：位于视频播放元素顶部并包含广告界面元素的容器对象。
AdsLoader：用于请求流并处理由流请求响应对象触发的事件的对象。您应该只实例化一个广告加载程序，该加载程序可在整个应用生命周期内重复使用。
StreamRequest：用于定义流请求的对象。视频流请求可以是视频点播请求，也可以是直播请求。直播请求会指定素材资源键，而 VOD 请求会指定 CMS ID 和视频 ID。这两种请求类型都可以选择性地包含访问指定视频流所需的 API 密钥，以及 Google Ad Manager 网络代码，以便 IMA SDK 按照 Google Ad Manager 设置中的指定方式处理广告标识符。
StreamManager：用于处理动态广告插播流以及与 DAI 后端互动的对象。流管理器还会处理跟踪 ping，并将流和广告事件转发给发布商。

前提条件

Android Studio
用于 SDK 集成的示例视频播放器应用

下载并运行示例视频播放器应用

此示例应用提供了一个可播放 HLS 视频的视频播放器。您可以使用此示例作为集成 IMA DAI SDK 的 DAI 功能的起点。

下载示例视频播放器应用并将其解压缩。
启动 Android Studio，然后选择 Open an existing Android Studio project；如果 Android Studio 已在运行，请依次选择 File > New > Import Project。然后选择 SampleVideoPlayer/build.gradle。
依次选择 Tools > Android > Sync Project with Gradle Files，运行 Gradle 同步。
确保播放器应用使用 Run > Run 'app' 在实体 Android 设备或 Android 虚拟设备上编译并运行。视频流在播放前需要几秒钟的加载时间，这是正常现象。

检查示例视频播放器

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

samplevideoplayer/SampleVideoPlayer.java：基于 ExoPlayer 的 HLS 播放器，可作为 IMA DAI 集成的基础。
videoplayerapp/MyActivity.java：此 activity 会创建视频播放器，并向其传递 Context 和 media3.ui.PlayerView。

将 IMA DAI SDK 添加到播放器应用

您还必须添加对 IMA DAI SDK 的引用。在 Android Studio 中，将以下内容添加到位于 app/build.gradle 的应用级 build.gradle 文件中。IMA SDK 需要启用库脱糖，您必须通过在 build.gradle 文件中设置 coreLibraryDesugaringEnabled true 并添加 coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.1.5' 作为依赖项来启用库脱糖。如需了解详情，请参阅通过脱糖提供的满足 Nio 规格要求的 Java 11 及更高版本 API。

repositories {
    google()
    mavenCentral()
}

dependencies {
    def media3_version = "1.5.1"
    implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))
    implementation 'androidx.appcompat:appcompat:1.7.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.7.0'
    implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.36.0'build.gradle

集成 IMA DAI SDK

在 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

创建 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

添加 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

您还需要一个 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

实现所需的监听器并添加对错误处理的支持。

请注意 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

添加用于记录日志的代码。

/** 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

修改 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

添加 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

修改 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 应用中请求和展示视频广告了。如需微调您的实现，请参阅书签、Snapback 和 API 文档。

问题排查

如果您在播放视频广告时遇到问题，请尝试下载完整的 BasicExample。如果该代码在 BasicExample 中可以正常运行，则可能是您的应用的 IMA 集成代码存在问题。

如果您仍遇到问题，请访问 IMA SDK 论坛。