IMA DAI SDK 使用入门

借助 IMA SDK,您可以轻松地将多媒体广告集成到您的网站和应用中。IMA SDK 可以从任何 符合 VAST 标准的广告服务器请求广告,并在您的应用中管理广告播放。借助 IMA DAI SDK,应用可针对广告和内容视频(VOD 或直播内容)发出视频流请求。然后,SDK 会返回合并的视频流,因此您无需在应用中管理广告和内容视频之间的切换。

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

IMA DAI 概览

实现 IMA DAI 涉及四个主要的 SDK 组件,本指南对此进行了演示:

  • StreamDisplayContainer:位于视频播放元素上方并容纳广告界面元素的容器对象。
  • AdsLoader:一个对象,用于请求数据流并处理由流请求响应对象触发的事件。 您应仅实例化一个广告加载器,该加载器可在应用的整个生命周期中重复使用。
  • StreamRequest:一个定义流请求的对象。流请求可以是视频点播请求,也可以是直播请求。请求会指定内容 ID、API 密钥或身份验证令牌和其他参数。
  • StreamManager:用于处理动态广告插播流以及与 DAI 后端的互动的对象。视频流管理器还会处理对 ping 的跟踪,并将视频流和广告事件转发给发布商。

前提条件

  • Android Studio
  • 您将用来集成 SDK 的示例视频播放器应用

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

示例应用提供了一个可播放 HLS 视频且可正常运行的视频播放器。如需开始集成 IMA Android SDK 的 DAI 功能,请先使用此参数。

  1. 下载示例视频播放器应用并解压缩。
  2. 启动 Android Studio 并选择 Open an existing Android Studio project;如果 Android Studio 已在运行,请依次选择 File > New > Import Project。然后选择 SampleVideoPlayer/build.gradle
  3. 如需运行 Gradle 同步,请依次选择 Tools > Android > Sync Project with Gradle Files
  4. 确保播放器应用可在实体 Android 设备或 Android 虚拟设备上通过 Run > Run 'app' 编译并运行。在播放视频流之前,视频流需要一些时间加载,这是正常现象。

检查示例视频播放器

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

  • samplevideoplayer/SampleVideoPlayer.java - 一个简单的基于 ExoPlayer 的 HLS 播放器,可用作 IMA DAI 集成的基础。
  • videoplayerapp/MyActivity.java - 此 Activity 会创建视频播放器,并向其传递 ContextSimpleExoPlayerView

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

此外,您还必须添加对 IMA SDK 的引用。在 Android Studio 中,将以下代码添加到位于 app/build.gradle 的应用级 build.gradle 文件:

repositories {
  google()
  jcenter()
}

dependencies {
    implementation 'androidx.appcompat:appcompat:1.2.0'
    implementation 'androidx.browser:browser:1.3.0'
    implementation 'com.google.android.exoplayer:exoplayer:2.19.0'
    implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.31.0'
}

检查点:您的应用应该能够编译并运行,但尚未添加用于请求和展示广告的界面元素或代码。
如果您的应用以 Android 11(API 级别 30)或更高版本为目标平台,则当前版本和最新版本的 IMA SDK 需要明确声明 intent 才能打开网页链接。将以下代码段添加到应用的清单文件中,使用户能够点击了解详情按钮,从而实现广告点击。
    <?xml version="1.0" encoding="utf-8"?>
    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
        package="com.example.project name">

        ...

        </application>

        <queries>
            <intent>
                <action android:name="android.intent.action.VIEW" />
                <data android:scheme="https" />
            </intent>
            <intent>
                <action android:name="android.intent.action.VIEW" />
                <data android:scheme="http" />
            </intent>
        </queries>
    </manifest>

集成 IMA SDK

  1. videoplayerapp 软件包(在 app/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/ 中)中创建一个名为 SampleAdsWrapper 的新类,以封装现有的 SampleVideoPlayer 并添加用于实现 IMA 动态广告插播 (DAI) 的逻辑。为此,您必须先创建一个 AdsLoader,用于向广告服务器请求广告。

    videoplayerapp/SampleAds 指封装容器.java

    package com.google.ads.interactivemedia.v3.samples.videoplayerapp;
    
    import android.annotation.TargetApi;
    import android.content.Context;
    import android.os.Build;
    import android.view.ViewGroup;
    import android.webkit.WebView;
    
    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.ImaSdkSettings;
    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.player.VideoProgressUpdate;
    import com.google.ads.interactivemedia.v3.api.player.VideoStreamPlayer;
    import com.google.ads.interactivemedia.v3.samples.samplevideoplayer.SampleVideoPlayer;
    
    import java.util.ArrayList;
    import java.util.HashMap;
    import java.util.List;
    
    public class SampleAdsWrapper implements AdEvent.AdEventListener,
            AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener {
    
        // Live stream asset key.
        private static final String TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA";
    
        // VOD content source and video IDs.
        private static final String TEST_CONTENT_SOURCE_ID = "2528370";
        private static final String TEST_VIDEO_ID = "tears-of-steel";
    
        private static final String PLAYER_TYPE = "DAISamplePlayer";
    
        /**
         * Log interface, so you can output the log commands to the UI or similar.
         */
        public interface Logger {
            void log(String logMessage);
        }
    
        private ImaSdkFactory sdkFactory;
        private AdsLoader adsLoader;
        private StreamDisplayContainer displayContainer;
        private StreamManager streamManager;
        private List<VideoStreamPlayer.VideoStreamPlayerCallback> playerCallbacks;
    
        private SampleVideoPlayer videoPlayer;
        private Context context;
        private ViewGroup adUiContainer;
    
        private String fallbackUrl;
        private Logger logger;
    
        public SampleAdsWrapper(Context context, SampleVideoPlayer videoPlayer,
                                ViewGroup adUiContainer) {
            this.videoPlayer = videoPlayer;
            this.context = context;
            this.adUiContainer = adUiContainer;
            sdkFactory = ImaSdkFactory.getInstance();
            playerCallbacks = new ArrayList<>();
            createAdsLoader();
            displayContainer = sdkFactory.createStreamDisplayContainer(
                this.adUiContainer,
                videoStreamPlayer
            );
        }
    
        private void createAdsLoader() {
            ImaSdkSettings settings = new ImaSdkSettings();
            adsLoader = sdkFactory.createAdsLoader(context);
        }
    
        public void requestAndPlayAds() {
            adsLoader.addAdErrorListener(this);
            adsLoader.addAdsLoadedListener(this);
            adsLoader.requestStream(buildStreamRequest());
        }
    }
              
  2. AdsLoader 添加 buildStreamRequest() 方法,以便请求包含广告的视频流。既可以是包含广告的直播(默认设置),也可以是播放预先录制且包含广告的内容的点播视频 (VOD) 流。如需启用 VOD 流,请注释掉直播请求并取消注释 VOD 视频流请求。

    videoplayerapp/SampleAds 指封装容器.java

    private StreamRequest buildStreamRequest() {
        VideoStreamPlayer videoStreamPlayer = createVideoStreamPlayer();
        videoPlayer.setSampleVideoPlayerCallback(
                new SampleVideoPlayer.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 you would seek past an ad, and if so, jump back to it.
                        long newSeekPositionMs = positionMs;
                        if (streamManager != null) {
                            CuePoint prevCuePoint  =
                                    streamManager.getPreviousCuePointForStreamTime(positionMs / 1000);
                            if (prevCuePoint != null && !prevCuePoint.isPlayed()) {
                                newSeekPositionMs = (long) (prevCuePoint.getStartTime() * 1000);
                            }
                        }
                        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);
                        }
                    }
                });
    
        // Live stream request.
        StreamRequest request = sdkFactory.createLiveStreamRequest(
                TEST_ASSET_KEY, null, displayContainer);
    
        // VOD request. Comment the createLiveStreamRequest() line above and uncomment this
        // createVodStreamRequest() below to switch from a live stream to a VOD stream.
        // StreamRequest request = sdkFactory.createVodStreamRequest(TEST_CONTENT_SOURCE_ID,
        //        TEST_VIDEO_ID, null, displayContainer);
        return request;
    }
    
  3. 您还需要一个 VideoStreamPlayer 来播放流,因此请添加 createVideoStreamPlayer() 方法,该方法会创建一个实现 VideoStreamPlayer 的匿名类。

    videoplayerapp/SampleAds 指封装容器.java

    private VideoStreamPlayer createVideoStreamPlayer() {
        VideoStreamPlayer player = new VideoStreamPlayer() {
            @Override
            public void loadUrl(String url, List<HashMap<String, String>> subtitles) {
                videoPlayer.setStreamUrl(url);
                videoPlayer.play();
            }
    
            @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.
                videoPlayer.enableControls(true);
                log("Ad Break Ended\n");
            }
    
            @Override
            public VideoProgressUpdate getContentProgress() {
                return new VideoProgressUpdate(videoPlayer.getCurrentPosition(),
                        videoPlayer.getDuration());
            }
        };
        return player;
    }
    
  4. 实现所需的监听器,并添加对错误处理的支持。

    重要提示:请注意 AdErrorListener 实现,因为在广告无法播放时它会调用后备网址。由于内容和广告位于同一个视频流中,因此如果 DAI 视频流发生错误,您必须准备好调用后备视频流。

    videoplayerapp/SampleAds 指封装容器.java

    /** AdErrorListener implementation **/
    @Override
    public void onAdError(AdErrorEvent event) {
        // play fallback URL.
        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 are 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;
    }
    
  5. 添加用于日志记录的代码。

    videoplayerapp/SampleAds 指封装容器.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);
        }
    }
    
  6. 修改 videoplayerapp 中的 MyActivity 以实例化并调用 SampleAdsWrapper

    videoplayerapp/MyActivity.java

    import android.view.ViewGroup;
    import android.widget.ScrollView;
    …
    public class MyActivity extends AppCompatActivity {
    …
        @Override
        protected void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);
            setContentView(R.layout.activity_my);
            View rootView = findViewById(R.id.videoLayout);
            videoPlayer = new SampleVideoPlayer(rootView.getContext(),
                    (SimpleExoPlayerView) rootView.findViewById(R.id.playerView));
            videoPlayer.enableControls(false);
    
            final SampleAdsWrapper sampleAdsWrapper = new SampleAdsWrapper(this, videoPlayer,
                (ViewGroup) rootView.findViewById(R.id.adUiContainer));
            sampleAdsWrapper.setFallbackUrl(DEFAULT_STREAM_URL);
    
            final ScrollView scrollView = (ScrollView) findViewById(R.id.logScroll);
            final TextView textView = (TextView) findViewById(R.id.logText);
    
            sampleAdsWrapper.setLogger(new SampleAdsWrapper.Logger() {
                @Override
                public void log(String logMessage) {
                    Log.i(APP_LOG_TAG, logMessage);
                    if (textView != null) {
                        textView.append(logMessage);
                    }
                    if (scrollView != null) {
                        scrollView.post(new Runnable() {
                            @Override
                            public void run() {
                                scrollView.fullScroll(View.FOCUS_DOWN);
                            }
                        });
                    }
                }
            });
    
            playButton = (ImageButton) rootView.findViewById(R.id.playButton);
            // Set up play button listener to play video then hide play button.
            playButton.setOnClickListener(new View.OnClickListener() {
                @Override
                public void onClick(View view) {
                    sampleAdsWrapper.requestAndPlayAds();
                    playButton.setVisibility(View.GONE);
                }
            });
        }
    …
    }
  7. 修改 Activity 的布局文件 activity_my.xml,以添加用于日志记录的界面元素。

    res/layout/activity_my.xml

    …
        <TextView
            android:id="@+id/playerDescription"
            android:text="@string/video_description"
            android:textAlignment="center"
            android:gravity="center_horizontal"
            android:layout_width="match_parent"
            android:layout_height="0dp"
            android:layout_weight="0.1"
            android:textSize="@dimen/font_size" />
        <!-- 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>
    

恭喜!现在,您在自己的 Android 应用中请求并显示视频广告。 如需微调实现,请参阅书签Snapback 指南,以及 API 文档

问题排查

如果您在播放视频广告时遇到问题,请尝试下载完成后的 BasicExample。如果它在 BasicExample 中可以正常运行,则可能是您应用的 IMA 集成代码存在问题。 请查看本指南和 API 文档,以检测任何差异。

仍然有问题?请在 IMA SDK 论坛上给我们留言。