ExoPlayer IMA uzantısını kullanmaya başlayın

ExoPlayer, Android için uygulama düzeyinde bir medya oynatıcıdır. Bu kılavuzda, hem reklam hem de içerik içeren bir medya akışı isteğinde bulunmak ve oynatmak için IMA DAI SDK'sını sarmalayan ExoPlayer IMA uzantısını nasıl kullanabileceğiniz gösterilmektedir.

Uzantının avantajlarından bazıları şunlardır:

• IMA'yı özelliklerle entegre etmek için gereken kodu basitleştirir.
• IMA'nın yeni sürümlerine güncelleme yapmak için gereken geliştirme süresini azaltır.

ExoPlayer IMA uzantısı, HLS ve DASH akış protokollerini destekler. Aşağıda bu sürecin bir özeti verilmiştir:

ExoPlayer-IMA uzantı akışı desteği
	Canlı yayın	Seç-izle yayınlar
HLS
DASH

DASH canlı yayınları, ExoPlayer-IMA 1.1.0 ve sonraki sürümlerde desteklenir.

Bu kılavuz, ExoPlayer kılavuzunu temel alır ve tam bir uygulamanın nasıl oluşturulacağını ve uzantının nasıl entegre edileceğini gösterir. Tam örnek uygulama içeren bir örnek için GitHub'daki ExoPlayerExample sayfasına bakın.

Önemli Bilgi: ExoPlayer IMA uzantısı, ExoPlayer'a bağlıdır. Farklı bir oynatıcı kullanmak istiyorsanız IMA DAI SDK'sını uygulamanıza entegre etmek için Başlangıç kılavuzunu uygulayın.

Ön koşullar

• Android Studio
• DAI desteği için AndroidX Media3 ExoPlayer 1.0.0 sürümü veya daha yeni bir sürüm.

Yeni bir Android Studio projesi oluşturma

Android Studio projenizi oluşturmak için aşağıdaki adımları uygulayın:

• Android Studio'yu başlatın.
• Yeni bir Android Studio projesi başlat'ı seçin.
• Projenizi seçin sayfasında Etkinlik yok şablonunu seçin.
• İleri'yi tıklayın.

• Projenizi yapılandırın sayfasında projenize bir ad verin ve dil olarak Java'yı seçin.

  Not: IMA DAI SDK'sı Kotlin ile uyumludur. Ancak bu kılavuzda ele alınan örnekte Java kullanılmaktadır.

• Son'u tıklayın.

ExoPlayer IMA uzantısını projenize ekleme

Uzantının içe aktarmalarını, uygulama düzeyindeki build.gradle dosyasının dependencies bölümüne ekleyin.

Uygulamanızı multidex'i etkinleştirecek şekilde yapılandırın. Bu, uzantının boyutu nedeniyle gereklidir ve minSdkVersion değeri Android 4.4W (API düzeyi 20) veya daha düşük bir sürüme ayarlanmış uygulamalar için zorunludur.

Aşağıda bununla ilgili bir örnek verilmiştir:

app/build.gradle

android {

  ...

  defaultConfig {
      applicationId "com.google.ads.interactivemedia.v3.samples.videoplayerapp"
      minSdkVersion 21
      targetSdkVersion 34
      multiDexEnabled true
      versionCode 1
      versionName "1.0"
  }

    ...
}
dependencies {
    implementation 'androidx.multidex:multidex:2.0.1'
    implementation 'androidx.media3:media3-ui:1.1.1'
    implementation 'androidx.media3:media3-exoplayer:1.1.1'
    implementation 'androidx.media3:media3-exoplayer-hls:1.1.1'
    implementation 'androidx.media3:media3-exoplayer-dash:1.1.1'

    // Adding the ExoPlayer IMA extension for ads will also include the IMA
    // SDK as a dependency.
    implementation 'androidx.media3:media3-exoplayer-ima:1.1.1'
}

Reklam istemek için IMA DAI SDK'sının gerektirdiği kullanıcı izinlerini ekleyin:

app/src/main/AndroidManifest.xml

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.project name">

    <!-- Required permissions for the IMA DAI SDK -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    ...

</manifest>

Intent beyanları ekleme

Uygulamanız Android 11 (API düzeyi 30) veya sonraki sürümleri hedefliyorsa IMA DAI SDK'sının mevcut ve son sürümleri, web bağlantılarını açma amacıyla açık bir beyan gerektirir. Reklam tıklamalarını (kullanıcıların Daha fazla bilgi düğmesini tıklaması) etkinleştirmek için aşağıdaki snippet'i uygulamanızın manifest dosyasına ekleyin.

Not: IMA DAI SDK'sının gelecekteki sürümleri bu beyanları otomatik olarak içerecek ve uygulamanızın manifest dosyasıyla birleştirilecektir.

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

ExoPlayer'ın kullanıcı arayüzünü ayarlama

ExoPlayer tarafından kullanılacak PlayerView nesnesini oluşturun.

androidx.constraintlayout.widget.ConstraintLayout değerini, ExoPlayer IMA uzantısı için önerilen LinearLayout olarak değiştirin.

Aşağıda bununla ilgili bir örnek verilmiştir:

app/src/main/res/layout/activity_my.xml

<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    android:background="@android:color/black"
    android:id="@+id/container"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    tools:context=".MyActivity"
    tools:ignore="MergeRootFrame">

    <androidx.media3.ui.PlayerView
        android:id="@+id/player_view"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

</LinearLayout>

Akış parametrelerinizi ekleme

Projenizi test etmek için örnek akış öğeleri için IMA örnek akış sayfasına bakın. Kendi akışlarınızı oluşturma hakkında bilgi edinmek için DAI'daki Ad Manager bölümüne de göz atın.

Bu adımda canlı yayın oluşturma gösterilmektedir ancak ExoPlayer IMA uzantısı DAI seç-izle yayınlarını da destekler. Uygulamanızın seç-izle video (VOD) yayınlarını işlemesi için yapması gereken değişiklikleri görmek üzere seç-izle video (VOD) yayınları için adımı inceleyin.

ExoPlayer IMA uzantısını içe aktarma

ExoPlayer uzantısı için içe aktarma ifadelerini ekleyin.

MyActivity.java'e aşağıdaki özel değişkenleri ekleyin:

• PlayerView
• ExoPlayer
• ImaServerSideAdInsertionMediaSource.AdsLoader
• ImaServerSideAdInsertionMediaSource.AdsLoader.State

Bu akışla test etmek için Big Buck Bunny (Canlı) HLS akışının öğe anahtarını ekleyin. IMA'nın örnek akış sayfasında test edebileceğiniz daha fazla akış vardır.

AdsLoader durumunu kaydetmek ve almak için bir KEY_ADS_LOADER_STATE sabit değeri oluşturun.

Aşağıda bununla ilgili bir örnek verilmiştir:

app/src/main/java/com/example/project name/MyActivity.java

import static androidx.media3.common.C.CONTENT_TYPE_HLS;

import android.app.Activity;
import android.net.Uri;
import android.os.Bundle;
import androidx.annotation.Nullable;
import androidx.annotation.OptIn;
import androidx.media3.common.MediaItem;
import androidx.media3.common.util.Util;
import androidx.media3.datasource.DataSource;
import androidx.media3.datasource.DefaultDataSource;
import androidx.media3.exoplayer.ExoPlayer;
import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionMediaSource;
import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionUriBuilder;
import androidx.media3.exoplayer.source.DefaultMediaSourceFactory;
import androidx.media3.exoplayer.util.EventLogger;
import androidx.media3.ui.PlayerView;
import androidx.multidex.MultiDex;

...

public class MyActivity extends Activity {

  private static final String KEY_ADS_LOADER_STATE = "ads_loader_state";
  private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";

  private PlayerView playerView;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;

}

adsLoader örneği oluşturma

PlayerView'u bulmak için onCreate yönteminin üzerine yazın ve adsLoader nesnesi başlatılırken kullanılabilecek kayıtlı bir AdsLoader.State olup olmadığını kontrol edin.

Ayrıca, uygulamanızın yöntem sayısı ve minSdkVersion gerektiriyorsa multidex'i etkinleştirin (2. adımda açıklandığı gibi).

Aşağıda bununla ilgili bir örnek verilmiştir:

app/src/main/java/com/example/project name/MyActivity.java

...

public class MyActivity extends Activity {

  private static final String KEY_ADS_LOADER_STATE = "ads_loader_state";
  private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";

  private PlayerView playerView;
  private ExoPlayer player;
  private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
  private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;

  @Override
  protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_my);
    MultiDex.install(this);

    playerView = findViewById(R.id.player_view);

    // Checks if there is a saved AdsLoader state to be used later when
    // initiating the AdsLoader.
    if (savedInstanceState != null) {
      Bundle adsLoaderStateBundle = savedInstanceState.getBundle(KEY_ADS_LOADER_STATE);
      if (adsLoaderStateBundle != null) {
        adsLoaderState =
            ImaServerSideAdInsertionMediaSource.AdsLoader.State.fromBundle(
                adsLoaderStateBundle);
      }
    }
  }

}

Oynatıcıyı başlatacak yöntemler ekleme

Oynatıcıyı başlatmak için bir yöntem ekleyin ve aşağıdakileri yapın:

• AdsLoader örneği oluşturun.
• ExoPlayer'yi oluşturun.
• Canlı yayının öğe anahtarıyla bir MediaItem oluşturun.
• MediaItem cihazını oynatıcınıza ayarlayın.

Not: Bu bölümde, sunucu tarafı reklam ekleme (SSAI) kavramlarına atıfta bulunan adlara sahip yöntemler kullanılmaktadır.

• Google Ad Manager DAI SSAI örneğidir.
• Bu kılavuzun ExoPlayer IMA uzantısı uygulaması, özellikle Ad Manager DAI ile çalışacak şekilde tasarlanmıştır. ExoPlayer IMA uzantıları, Google Cloud Platform gibi bu kılavuzda gösterilmeyen diğer SSAI örneklerini de destekler.

Aşağıda bununla ilgili bir örnek verilmiştir:

app/src/main/java/com/example/project name/MyActivity.java

public class MyActivity extends Activity {

  ...

  
  // Create a server side ad insertion (SSAI) AdsLoader.
  private ImaServerSideAdInsertionMediaSource.AdsLoader createAdsLoader() {
    ImaServerSideAdInsertionMediaSource.AdsLoader.Builder adsLoaderBuilder =
        new ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(this, playerView);

    // Attempt to set the AdsLoader state if available from a previous session.
    if (adsLoaderState != null) {
      adsLoaderBuilder.setAdsLoaderState(adsLoaderState);
    }

    return adsLoaderBuilder.build();
  }

  private void initializePlayer() {
    adsLoader = createAdsLoader();

    // Set up the factory for media sources, passing the ads loader.
    DataSource.Factory dataSourceFactory = new DefaultDataSource.Factory(this);
    DefaultMediaSourceFactory mediaSourceFactory = new DefaultMediaSourceFactory(dataSourceFactory);

    // MediaSource.Factory to create the ad sources for the current player.
    ImaServerSideAdInsertionMediaSource.Factory adsMediaSourceFactory =
        new ImaServerSideAdInsertionMediaSource.Factory(adsLoader, mediaSourceFactory);

    // 'mediaSourceFactory' is an ExoPlayer component for the DefaultMediaSourceFactory.
    // 'adsMediaSourceFactory' is an ExoPlayer component for a MediaSource factory for IMA server
    // side inserted ad streams.
    mediaSourceFactory.setServerSideAdInsertionMediaSourceFactory(adsMediaSourceFactory);

    // Create an ExoPlayer and set it as the player for content and ads.
    player = new ExoPlayer.Builder(this).setMediaSourceFactory(mediaSourceFactory).build();
    playerView.setPlayer(player);
    adsLoader.setPlayer(player);

    // Build an IMA SSAI media item to prepare the player with.
    Uri ssaiLiveUri =
        new ImaServerSideAdInsertionUriBuilder()
            .setAssetKey(SAMPLE_ASSET_KEY)
            .setFormat(CONTENT_TYPE_HLS) // Use CONTENT_TYPE_DASH for dash streams.
            .build();

    // Create the MediaItem to play, specifying the stream URI.
    MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiLiveUri);

    // Prepare the content and ad to be played with the ExoPlayer.
    player.setMediaItem(ssaiMediaItem);
    player.prepare();

    // Set PlayWhenReady. If true, content and ads will autoplay.
    player.setPlayWhenReady(false);
  }
}

Oynatıcıyı serbest bırakmak için bir yöntem ekleme

Oynatıcıyı bu sırada serbest bırakacak bir yöntem ekleyin:

• Oyuncu referanslarını null olarak ayarlayın ve oyuncunun kaynaklarını serbest bırakın.
• adsLoader durumunu bırakın.

app/src/main/java/com/example/project name/MyActivity.java

public class MyActivity extends Activity {

  ...

  private void releasePlayer() {
    // Set the player references to null and release the player's resources.
    playerView.setPlayer(null);
    player.release();
    player = null;

    // Release the adsLoader state so that it can be initiated again.
    adsLoaderState = adsLoader.release();
  }

Oyuncu etkinliklerini işleme

Son olarak, oynatma akışını yönetmek için etkinliğin yaşam döngüsü etkinlikleri için geri aramalar oluşturun.

Android SDK 24 ve sonraki sürümleri desteklemek için:

• onStart()
• onStop()

24'ten eski Android SDK sürümlerini desteklemek için: - onResume() - onPause()

onStart() ve onResume(), playerView.onResume() ile eşlenir. onStop() ve onPause() ise playerView.onPause() ile eşlenir.

Önemli Bilgi: Bu örnek, hem Android SDK 24 ve sonraki sürümleri hem de 24'ten önceki sürümleri desteklemeyi amaçlamaktadır. Android SDK'sı 24 ve sonraki sürümler için onStart()/onStop(), 24'ten önceki sürümler için onResume()/onPause() kullanın.

Bu adımda, adsLoaderState öğesini kaydetmeye çalışmak için onSaveInstanceState() etkinliği de kullanılır.

app/src/main/java/com/example/project name/MyActivity.java

public class MyActivity extends Activity {

  ...

  @Override
  public void onStart() {
    super.onStart();
    if (Util.SDK_INT > 23) {
      initializePlayer();
      if (playerView != null) {
        playerView.onResume();
      }
    }
  }

  @Override
  public void onResume() {
    super.onResume();
    if (Util.SDK_INT <= 23 || player == null) {
      initializePlayer();
      if (playerView != null) {
        playerView.onResume();
      }
    }
  }

  @Override
  public void onPause() {
    super.onPause();
    if (Util.SDK_INT <= 23) {
      if (playerView != null) {
        playerView.onPause();
      }
      releasePlayer();
    }
  }

  @Override
  public void onStop() {
    super.onStop();
    if (Util.SDK_INT > 23) {
      if (playerView != null) {
        playerView.onPause();
      }
      releasePlayer();
    }
  }

  @Override
  public void onSaveInstanceState(Bundle outState) {
    // Attempts to save the AdsLoader state to handle app backgrounding.
    if (adsLoaderState != null) {
      outState.putBundle(KEY_ADS_LOADER_STATE, adsLoaderState.toBundle());
    }
  }

  ...

}

Seç-izle akışı kurulumu (isteğe bağlı)

Uygulamanızın seç-izle video içeriğini reklamlarla oynatması gerekiyorsa aşağıdakileri yapmanız gerekir:

1. VOD test akışı için bir CMS ID ve Video ID ekleyin.
2. ImaServerSideAdInsertionUriBuilder() kullanarak SSAI VOD URI'si oluşturun.
3. Oynatıcınızın medya öğesi olarak bu yeni URI'yi kullanın.

app/src/main/java/com/example/project name/MyActivity.java

public class MyActivity extends Activity {

  private static final String KEY_ADS_LOADER_STATE = "ads_loader_state";
  private static final String SAMPLE_ASSET_KEY = "c-rArva4ShKVIAkNfy6HUQ";
  private static final String SAMPLE_CMS_ID = "2548831";
  private static final String SAMPLE_VIDEO_ID = "tears-of-steel";

  ...

  private void initializePlayer() {

     ...

    Uri ssaiVodUri =
        new ImaServerSideAdInsertionUriBuilder()
            .setContentSourceId(SAMPLE_CMS_ID)
            .setVideoId(SAMPLE_VIDEO_ID)
            .setFormat(CONTENT_TYPE_HLS)
            .build();

    // Create the MediaItem to play, specifying the stream URI.
    MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiVodUri);

    // Prepare the content and ad to be played with the ExoPlayer.
    player.setMediaItem(ssaiMediaItem);
    player.prepare();

    // Set PlayWhenReady. If true, content and ads will autoplay.
    player.setPlayWhenReady(false);
  }

İşte bu kadar. Artık ExoPlayer IMA uzantısını kullanarak medya akışı isteğinde bulunuyor ve oynatıyorsunuz. Kodun tamamı için GitHub'daki Android DAI örneklerine göz atın.