이 페이지는 Cloud Translation API를 통해 번역되었습니다.

IMA DAI SDK 시작하기

IMA SDK를 사용하면 멀티미디어 광고를 웹사이트와 앱에 쉽게 통합할 수 있습니다. IMA SDK는 VAST 호환 광고 서버에서 광고를 요청하고, 앱에서 광고 재생을 관리할 수 있습니다. IMA DAI SDK를 사용하면 앱에서 광고 및 콘텐츠 동영상(VOD 또는 라이브 콘텐츠)의 스트림을 요청합니다. 그러면 SDK가 결합된 동영상 스트림을 반환하므로 앱 내에서 광고와 콘텐츠 동영상 간의 전환을 관리할 필요가 없습니다.

관심 있는 DAI 솔루션 선택하기

전체 서비스 DAI

이 가이드에서는 IMA DAI SDK를 간단한 동영상 플레이어 앱에 통합하는 방법을 설명합니다. 완료된 샘플 통합을 보거나 따라 하려면 GitHub에서 BasicExample을 다운로드하세요.

IMA DAI 개요

IMA DAI 구현에는 이 가이드에 설명된 네 가지 주요 SDK 구성요소가 포함됩니다.

StreamDisplayContainer: 동영상 재생 요소 위에 배치되고 광고 UI 요소를 수용하는 컨테이너 객체입니다.
AdsLoader: 스트림을 요청하고 스트림 요청 응답 객체에 의해 트리거된 이벤트를 처리하는 객체입니다. 애플리케이션의 수명 주기 내내 재사용할 수 있는 하나의 광고 로더만 인스턴스화해야 합니다.
StreamRequest: 스트림 요청을 정의하는 객체입니다. 스트림 요청은 VOD 또는 실시간 스트림일 수 있습니다. 요청에서 콘텐츠 ID, API 키 또는 인증 토큰, 기타 매개변수를 지정합니다.
StreamManager: 동적 광고 삽입 스트림 및 DAI 백엔드와의 상호작용을 처리하는 객체입니다. 또한 스트림 관리자는 추적 핑을 처리하고 스트림 및 광고 이벤트를 게시자에게 전달합니다.

기본 요건

Android 스튜디오
SDK 통합용 샘플 동영상 플레이어 앱

샘플 동영상 플레이어 앱 다운로드 및 실행

샘플 앱은 HLS 동영상을 재생하는 작동하는 동영상 플레이어를 제공합니다. 이를 IMA DAI SDK의 DAI 기능 통합을 위한 시작점으로 사용하세요.

샘플 동영상 플레이어 앱을 다운로드하고 압축을 풉니다.
Android 스튜디오를 시작하고 Open an existing Android Studio project를 선택하거나 Android 스튜디오가 이미 실행 중인 경우 File > New > Import Project를 선택합니다. 그런 다음 SampleVideoPlayer/build.gradle를 선택합니다.
Tools > Android > Sync Project with Gradle Files를 선택하여 Gradle 동기화를 실행합니다.
Run > Run 'app'을 사용하여 플레이어 앱이 실제 Android 기기 또는 Android Virtual Device에서 컴파일되고 실행되는지 확인합니다. 일반적으로 동영상 스트림이 재생되기 전에 로드되는 데 잠시 시간이 걸립니다

샘플 동영상 플레이어 확인

샘플 동영상 플레이어에는 아직 IMA DAI SDK 통합 코드가 없습니다. 샘플 앱은 두 가지 주요 부분으로 구성됩니다.

samplevideoplayer/SampleVideoPlayer.java: IMA DAI 통합의 기반 역할을 하는 ExoPlayer 기반 HLS 플레이어입니다.
videoplayerapp/MyActivity.java: 이 활동은 동영상 플레이어를 만들고 Context 및 SimpleExoPlayerView를 전달합니다.

플레이어 앱에 IMA DAI SDK 추가

IMA DAI SDK에 대한 참조도 포함해야 합니다. Android 스튜디오에서 app/build.gradle에 있는 애플리케이션 수준 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.33.0'
}

IMA DAI SDK 통합

videoplayerapp 패키지(app/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/에서)에 SampleAdsWrapper라는 새 클래스를 만들어 기존 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 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도 필요하므로 VideoStreamPlayer를 구현하는 익명 클래스를 만드는 createVideoStreamPlayer() 메서드를 추가합니다.

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());
        }
    };
    return player;
}

필수 리스너를 구현하고 오류 처리를 위한 지원을 추가합니다.

AdErrorListener 구현은 광고가 재생되지 않으면 대체 URL을 호출하므로 확인하세요. 콘텐츠와 광고가 하나의 스트림에 있으므로 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을 다운로드해 보세요. BasicExample에서 제대로 작동하면 앱의 IMA 통합 코드에 문제가 있을 가능성이 높습니다.

문제가 계속되면 IMA SDK 포럼을 방문하세요.