Bu sayfa, Cloud Translation API ile çevrilmiştir.

DAI için IMA SDK'sını ayarlama

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 hizmetli 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. Canlı yayın istekleri bir öğe anahtarı belirtirken VOD istekleri bir İYS kimliği ve video kimliği belirtir. Her iki istek türü de isteğe bağlı olarak, belirtilen akışlara erişmek için gereken bir API anahtarı ve IMA SDK'sının Google Ad Manager ayarlarında belirtildiği gibi reklam tanımlayıcılarını işleyebilmesi için bir Google Ad Manager ağ kodu içerebilir.
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.

Örnek video oynatıcı uygulamasını indirip açın.
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.
Araçlar > Android > Projeyi Gradle Dosyalarıyla Senkronize Et'i seçerek Gradle senkronizasyonu çalıştırın.
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:

samplevideoplayer/SampleVideoPlayer.java: IMA DAI entegrasyonunun temelini oluşturan ExoPlayer tabanlı bir HLS oynatıcı.
videoplayerapp/MyActivity.java: Bu etkinlik, video oynatıcıyı oluşturur ve Context ile media3.ui.PlayerView 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 {
    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'sını entegre etme

Mevcut SampleVideoPlayer'ı sarmalamak ve IMA DAI'yi 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 DAI akışını istemek üzere kullanılan bir AdsLoader oluşturmanız gerekir.

Bu snippet, HLS ve DASH, canlı ve VOD akışları için örnek parametreler içerir. Hangi yayının oynatıldığını ayarlamak için CONTENT_TYPE değişkenini güncelleyin.

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

VideoStreamPlayer.VideoStreamPlayerCallback'ı genişleten bir SampleVideoPlayerCallback arayüzü örneği oluşturmayı yönetmek için bir createSampleVideoPlayerCallback() yardımcı yöntemi oluşturun.

DAI ile çalışmak için oynatıcının canlı yayınlar için ID3 etkinliklerini IMA DAI SDK'sına iletmesi gerekir. Aşağıdaki örnek kodda callback.onUserTextReceived() yöntemi bunu yapar.

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

SteamRequest oluşturmak için bir buildStreamRequest() yöntemi ekleyin. Bu yöntem, CONTENT_TYPE değişkenini nasıl ayarladığınıza bağlı olarak farklı akışlar arasında geçiş yapar. Bu kılavuzda kullanılan varsayılan akış, IMA'nın örnek VOD HLS akışıdır.

@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

Akış oynatmak için bir VideoStreamPlayer'ye de ihtiyacınız vardır. Bu nedenle, VideoStreamPlayer'yi uygulayan anonim bir sınıf oluşturan bir createVideoStreamPlayer() yöntemi ekleyin.

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

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.

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

Günlüğe kaydetme kodu ekleyin.

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

SampleAdsWrapper nesnesi oluşturmak ve çağırmak için videoplayerapp içindeki MyActivity öğesini değiştirin. Ayrıca, bir ImaSdkSettings örneği oluşturmak için yardımcı yöntem kullanarak burada ImaSdkFactory.initialize() çağrısı yapın.

Önemli: IMA yükleme sürelerini iyileştirmek için ImaSdkFactory.initialize() yöntemini uygulama yaşam döngüsünün mümkün olduğunca erken bir aşamasında çağırın. Yöntemi erken çağırmak, IMA'nın ilk akış isteğinde bulunmadan önce gerekli kaynakları yükleme süresini en üst düzeye çıkarır. ImaSdkFactory.initialize() yöntem çağrısı bir ImaSdkSettings örneğini kabul eder. Burada ve AdsLoader örneği oluştururken aynı ayar değerlerini kullandığınızdan emin olun. Bu örnekte, ayar değerlerinin aynı olduğundan emin olmak için getImaSdkSettings() yardımcı yöntemi kullanılır. Daha fazla bilgi için IMA yükleme süresini optimize etme kılavuzu>na göz atın.

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

ImaSdkSettings örneği oluşturmak için getImaSdkSettings() yardımcı yöntemini ekleyin.

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

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.

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

Tebrikler! Artık Android uygulamanızda video reklam isteğinde bulunuyor ve video reklamları gösteriyorsunuz. Uygulamanızın ayrıntılarını ayarlamak için Başlıklar, Geri dön 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.