本頁面由 Cloud Translation API 翻譯而成。

開始使用 IMA DAI SDK

IMA SDK 可讓您輕鬆將多媒體廣告整合至您的網站和應用程式。IMA SDK 可以向任何與 VAST 相容的廣告伺服器，並管理您應用程式中的廣告播放方式。使用 IMA DAI SDK 時，應用程式可提供廣告和內容影片的串流請求 (VOD 或直播內容)。接著，SDK 會傳回讓您省去切換廣告和內容影片的麻煩應用程式內的一切

選取所需的 DAI 解決方案

完整服務 DAI

本指南說明如何將 IMA DAI SDK 整合到簡易影片播放器中應用程式。如果您要檢視或繼續完成樣本請從中下載 BasicExample GitHub。

IMA DAI 總覽

導入 IMA DAI 時，必須完成四個主要的 SDK 元件，如下所示指南：

StreamDisplayContainer: 這個容器物件位於影片播放元素上方，並存放廣告 UI 元素。
AdsLoader: 這個物件會要求串流及處理串流要求回應物件觸發的事件。您只應將一個廣告載入器執行個體化，且該載入器在整個生命週期內可以重複使用應用程式。
StreamRequest: 定義串流要求的物件。串流要求可以是隨選影片或直播串流。要求會指明內容 ID 以及 API 金鑰或驗證權杖等參數。
StreamManager: 這個物件會處理動態廣告插播串流，以及與 DAI 後端的互動。串流管理員也會處理追蹤連線偵測 (ping)，並將串流和廣告事件轉送至內容。

必要條件

Android Studio
SDK 整合的影片播放器應用程式範例

下載並執行範例影片播放器應用程式

範例應用程式提供可以播放 HTTP 即時串流影片的影片播放器。使用做為導入 IMA DAI SDK 的 DAI 功能的起點。

下載範例影片播放器應用程式和解壓縮。
啟動 Android Studio，然後選取「Open an existing Android Studio project」，如果 Android Studio 已在執行中，請依序選取「File」>新增 >匯入專案。然後選擇 SampleVideoPlayer/build.gradle。
依序選取「Tools」>「Tools」即可執行 Gradle 同步處理作業。Android >將專案與 Gradle 檔案同步處理。
確保玩家應用程式可編譯並執行在實體 Android 裝置上，或使用 Run > 安裝的 Android 虛擬裝置執行「app」。影片是正常的可能需要幾分鐘的時間才會載入

查看影片播放器範例

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

samplevideoplayer/SampleVideoPlayer.java：以 ExoPlayer 為基礎的 HLS 播放器，。
videoplayerapp/MyActivity.java：此活動會建立影片播放器，並傳遞 Context 和 SimpleExoPlayerView。

在播放器應用程式中新增 IMA DAI SDK

您也必須加入 IMA DAI SDK 的參照。在 Android Studio 中新增加到應用程式層級的 build.gradle 檔案 (位於 app/build.gradle：

repositories {
  google()
  mavenCentral()
}

dependencies {
    implementation 'androidx.appcompat:appcompat:1.6.1'
    implementation 'androidx.media3:media3-exoplayer:1.3.1'
    implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.34.0'
}

整合 IMA DAI SDK

在 videoplayerapp 套件中建立名為 SampleAdsWrapper 的新類別 (於app/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/) 變更為納入現有的 SampleVideoPlayer 並新增導入 IMA DAI 的邏輯。目的地：如要執行這項操作，您必須先建立用來請求廣告的 AdsLoader 來自廣告伺服器

videoplayerapp/SampleAdsWrapper.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 {

    // Livestream 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 = "2548831";
    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());
    }
}

將 buildStreamRequest() 方法新增至 AdsLoader，以要求直播 (含廣告)這些內容是含有廣告的直播 (預設設定) 或隨選影片(VOD) 串流，播放含有廣告的預錄內容。目的地：啟用 VOD 串流、在直播請求中留言，並將 VOD 串流請求。

如要與 DAI 搭配使用，播放器必須將直播影片的 ID3 事件傳遞至 IMA DAI 透過筆記本工具 Vertex AI Workbench 您能使用 SDK 定義自己的管線在以下範例程式碼中，系統會透過 callback.onUserTextReceived() 方法。

videoplayerapp/SampleAdsWrapper.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);
                    }
                }
            });

    // Livestream 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 livestream to a VOD stream.
    // StreamRequest request = sdkFactory.createVodStreamRequest(TEST_CONTENT_SOURCE_ID,
    //        TEST_VIDEO_ID, null, displayContainer);
    return request;
}

還需要 VideoStreamPlayer 才能播放串流，因此請新增 createVideoStreamPlayer() 方法，可建立匿名類別，實作 VideoStreamPlayer。

videoplayerapp/SampleAdsWrapper.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());
        }

        @Override
        public int getVolume() {
            return videoPlayer.getVolume();
        }
    };
    return player;
}

實作必要的事件監聽器，並新增錯誤處理支援功能。

請留意 AdErrorListener 實作，因為如果廣告無法播放。由於內容和廣告位於同一個串流中，因此您必須，如果 DAI 串流發生錯誤，就會呼叫備用串流。

videoplayerapp/SampleAdsWrapper.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;
}

新增記錄功能的程式碼。

videoplayerapp/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);
    }
}

修改 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);
            }
        });
    }
...
}

修改活動的版面配置檔案 activity_my.xml，新增以下應用程式的 UI 元素：。

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。如果基本範例可以正常運作，表示您的的 IMA 整合程式碼。

如果問題仍未解決，請參閱 IMA SDK 論壇。