IMA DAI SDK'sını kullanmaya başlama

IMA SDK'ları, multimedya reklamları web sitelerinize ve uygulamalarınıza entegre etmenizi kolaylaştırır. IMA SDK'ları, VAST ile uyumlu herhangi bir reklam sunucusundan reklam isteyebilir ve uygulamalarınızda reklam oynatmayı yönetebilir. IMA DAI SDK'ları ile uygulamalar, reklam ve içerik videosu (VOD veya canlı içerik) için bir yayın isteği gönderir. Ardından SDK, birleştirilmiş bir video akışı döndürür. Böylece uygulamanızda reklam ve içerik videosu arasında geçiş yapmanız gerekmez.

İlgilendiğiniz DAI çözümünü seçin

Tam kapsamlı DAI

Bu kılavuzda, IMA DAI SDK'sının basit bir video oynatıcı uygulamasına nasıl entegre edileceği gösterilmektedir. Tamamlanmış bir örnek entegrasyonu görüntülemek veya takip etmek istiyorsanız GitHub'dan BasicExample dosyasını indirin.

IMA DAI'ye genel bakış

IMA DAI'yi uygulamak, bu kılavuzda gösterildiği gibi dört ana SDK bileşenini içerir:

  • StreamDisplayContainer: Video oynatma öğesinin üzerinde bulunan ve reklam kullanıcı arayüzü öğelerini barındıran bir kapsayıcı nesnesi.
  • AdsLoader: Akış isteğinde bulunan ve akış isteği yanıtı nesneleri tarafından tetiklenen etkinlikleri işleyen bir nesne. Uygulamanın ömrü boyunca yeniden kullanılabilecek tek bir reklam yükleyicisi oluşturmanız gerekir.
  • StreamRequest: Akış isteğini tanımlayan bir nesne. Akış istekleri, seç-izle videolar veya canlı yayınlar için olabilir. İstekler, bir içerik kimliğinin yanı sıra API anahtarı veya kimlik doğrulama jetonu ve diğer parametreleri belirtir.
  • StreamManager: Dinamik reklam ekleme akışlarını ve DAI arka ucuyla etkileşimleri yöneten bir nesne. Yayın yöneticisi, izleme ping'lerini de yönetir ve yayın ile reklam etkinliklerini yayıncıya iletir.

Ön koşullar

  • Android Studio
  • SDK entegrasyonu için örnek video oynatıcı uygulaması

Örnek video oynatıcı uygulamasını indirip çalıştırma

Örnek uygulama, HLS video oynatan çalışan bir video oynatıcı sağlar. IMA DAI SDK'sının DAI özelliklerini entegre etmek için bunu başlangıç noktası olarak kullanın.

  1. Örnek video oynatıcı uygulamasını indirip açın.

  2. Android Studio'yu başlatın ve Mevcut bir Android Studio projesini aç'ı seçin veya Android Studio zaten çalışıyorsa Dosya > Yeni > Projeyi İçe Aktar'ı seçin. Ardından SampleVideoPlayer/build.gradle simgesini seçin.

  3. Araçlar > Android > Projeyi Gradle Dosyalarıyla Senkronize Et'i seçerek Gradle senkronizasyonu çalıştırın.

  4. Oynatıcı uygulamasının, Çalıştır > "uygulama"yı çalıştır'ı kullanarak fiziksel bir Android cihazda veya Android sanal cihazda derlendiğinden ve çalıştığından emin olun. Video akışının oynatılmadan önce yüklenmesi birkaç dakika sürebilir.

Örnek video oynatıcıyı inceleme

Örnek video oynatıcı henüz IMA DAI SDK entegrasyon kodu içermiyor. Örnek uygulama iki ana bölümden oluşur:

  1. samplevideoplayer/SampleVideoPlayer.java: IMA DAI entegrasyonunun temelini oluşturan ExoPlayer tabanlı bir HLS oynatıcı.

  2. videoplayerapp/MyActivity.java: Bu etkinlik, video oynatıcıyı oluşturur ve Context ile SimpleExoPlayerView parametrelerini iletir.

IMA DAI SDK'sını oynatıcı uygulamasına ekleme

IMA DAI SDK'sına da referans eklemeniz gerekir. Android Studio'da, app/build.gradle adresindeki uygulama düzeyindeki build.gradle dosyanıza aşağıdakileri ekleyin:

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.36.0'
}

IMA DAI SDK'sını entegre etme

  1. Mevcut SampleVideoPlayer'ı sarmalamak ve IMA DAI'yı uygulayan mantık eklemek için videoplayerapp paketinde (app/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/ içinde) SampleAdsWrapper adlı yeni bir sınıf oluşturun. Bunu yapmak için öncelikle reklam sunucularından reklam istemek üzere kullanılan bir AdsLoader oluşturmanız gerekir.

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

  2. Reklam içeren bir akış isteğinde bulunabilmesi için AdsLoader yöntemine bir buildStreamRequest() yöntemi ekleyin. Bu, reklamlı bir canlı yayın (varsayılan olarak ayarlanır) veya önceden kaydedilmiş içeriği reklamlarla oynatan bir talep üzerine video(VOD) akışı olabilir. VOD yayınını etkinleştirmek için canlı yayın isteğini yoruma alın ve VOD yayın isteği için yorumu kaldırın.

    DAI ile çalışmak için oynatıcıların, canlı yayınlar için ID3 etkinliklerini IMA DAI SDK'larına iletmesi gerekir. Aşağıdaki örnek kodda bu işlem callback.onUserTextReceived() yöntemiyle yapılır.

    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;
}

  3. Akış oynatmak için bir VideoStreamPlayer da gerekir. Bu nedenle, VideoStreamPlayer uygulayan anonim bir sınıf oluşturan bir createVideoStreamPlayer() yöntemi ekleyin.

    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;
}

  4. Gerekli dinleyicileri uygulayın ve hata işleme desteği ekleyin.

    Reklamlar oynatılamıyorsa yedek URL'yi çağırdığı için AdErrorListener uygulamasını not edin. İçerik ve reklamlar tek bir akışta olduğundan, DAI akışında bir hata oluşursa yedek akışı çağırmaya hazır olmanız gerekir.

    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;
}

  5. Günlüğe kaydetme kodu ekleyin.

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

  6. SampleAdsWrapper sınıfını örneklemek ve çağırmak için videoplayerapp içindeki MyActivity öğesini değiştirin.

    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. Günlüğe kaydetme için kullanıcı arayüzü öğeleri eklemek üzere Etkinlik'in activity_my.xml düzen dosyasını değiştirin.

    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>
...

Tebrikler! Artık Android uygulamanızda video reklam isteğinde bulunuyor ve video reklamları gösteriyorsunuz. Uygulamanızın işleyişine ince ayar yapmak için Başlıklar, Geri alma ve API dokümanlarına göz atın.

Sorun giderme

Video reklam oynatırken sorun yaşıyorsanız tamamlanmış BasicExample dosyasını indirmeyi deneyin. BasicExample'da düzgün çalışıyorsa büyük olasılıkla uygulamanızın IMA entegrasyon kodunda bir sorun vardır.

Sorun yaşamaya devam ederseniz IMA SDK forumunu ziyaret edin.