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 reklamlar hem de içeriğe sahip bir medya akışı istemek ve oynatmak için IMA Android 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 kısaltır.

ExoPlayer IMA uzantısı, HLS ve DASH akış protokollerini destekler. Özetle:

ExoPlayer-IMA uzantısı akış desteği
	Canlı yayın	VOD akışları
HLS
DASH

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

ExoPlayer kılavuzuna dayalı bu kılavuzda, tam bir uygulamanın nasıl oluşturulacağı ve uzantının nasıl entegre edileceği gösterilmektedir. Eksiksiz bir örnek uygulamayı içeren bir örnek için GitHub'daki ExoPlayerExample belgesine göz atın.

Önemli Bilgi: ExoPlayer IMA uzantısı ExoPlayer'a bağlıdır. Farklı bir oynatıcı kullanmayı tercih ederseniz IMA DAI SDK'sını uygulamanıza entegre etmek için Başlangıç kılavuzunu takip edin.

Ön koşullar

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

Yeni Android Studio projesi oluşturma

Android Studio projenizi oluşturmak için aşağıdaki adımları tamamlayı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ılmıştır.

• Son'u tıklayın.

Projenize ExoPlayer IMA uzantısını ekleyin

dependencies bölümünde, uygulama düzeyindeki build.gradle dosyasına uzantıyla ilgili içe aktarmalar ekleyin.

Uygulamanızı multidex'e yapılandırın ve etkinleştirin. Bu, uzantının boyutu nedeniyle ve minSdkVersion özelliği Android 4.4W (API düzeyi 20) veya daha düşük bir seviyeye ayarlanmış uygulamalar için gereklidir.

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

app/build.gradle

android {

  ...

  defaultConfig {
      applicationId "com.google.ads.interactivemedia.v3.samples.videoplayerapp"
      minSdkVersion 19
      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'
}

IMA SDK'nın reklam isteğinde bulunmak için ihtiyaç duyduğu 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 SDK -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

    ...

</manifest>

Amaç bildirimleri ekle

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

Not: IMA SDK'sının gelecek sürümleri bu bildirimleri otomatik olarak içerecek ve uygulamanızın manifest dosyasıyla birleştirilecek.

  <?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ü ayarlayın

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

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

Aşağıda 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 üzere örnek akış öğeleri için IMA örnek akış sayfasına bakın. Kendi akışlarınızı ayarlama hakkında bilgi için DAI hakkındaki Ad Manager bölümüne de bakın.

Bu adımda, bir canlı yayının ayarlanması gösterilmektedir ancak ExoPlayer IMA uzantısı da DAI VOD akışlarını destekler. Uygulamanızın VOD akışlarını ele almak için hangi değişikliklere ihtiyacı olduğunu görmek için seç-izle video (VOD) akışları adımına bakın.

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

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

Aşağıdaki gizli değişkenleri MyActivity.java öğesine ekleyin:

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

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

AdsLoader durumunu kaydetmek ve almak için bir KEY_ADS_LOADER_STATE sabiti oluşturun.

Aşağıda 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şturun

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

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

Aşağıda 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.CREATOR.fromBundle(
                adsLoaderStateBundle);
      }
    }
  }

}

Oynatıcıyı başlatmak için yöntemler ekleyin

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

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

Not: Bu bölümde, adlarda sunucu tarafı reklam ekleme (SSAI) kavramlarına referans veren yöntemler kullanılmaktadır.

• Google Ad Manager DAI bir 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ı, bu kılavuzda gösterilmeyen Google Cloud Platform gibi diğer SSAI örneklerini de destekler.

Aşağıda 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 ekleyin

Oynatıcıyı bu sırada serbest bırakmak için bir yöntem ekleyin:

• Oynatıcı referanslarını null değerine ayarlayın ve oynatıcının kaynaklarını serbest bırakın.
• adsLoader durumunu serbest 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();
  }

Oynatıcı etkinliklerini yönetin

Son olarak, akış oynatma işlemini gerçekleştirmek amacıyla etkinliğin yaşam döngüsü olayları için geri çağırmalar 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, onStop() ve onPause() ise playerView.onPause() ile eşleniyor.

Önemli Nokta: Bu örnekte, Android SDK 24 ve üzeri sürümler ile 24'ten önceki sürümlerin desteklenmesi amaçlanmaktadır. Android SDK 24 ve sonraki sürümler için onStart()/onStop(), 24 ve üzeri sürümler için onResume()/onPause() kodunu kullanın.

Bu adım, adsLoaderState öğesini kaydetmeyi denemek için onSaveInstanceState() etkinliğini de kullanı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());
    }
  }

  ...

}

VOD akış kurulumu (isteğe bağlı)

Uygulamanızın reklamlarla birlikte VOD içeriği oynatması gerekiyorsa aşağıdakileri yapmanız gerekir:

1. VOD test akışı için CMS ID ve Video ID ekleyin.
2. ImaServerSideAdInsertionUriBuilder() kullanarak bir SSAI VOD URI'si oluşturun.
3. Bu yeni URI'yı oynatıcınızın medya öğesi olarak 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 = "2528370";
  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. Şu anda ExoPlayer IMA uzantısıyla bir medya akışı ister ve oynatırsınız. Kodun tamamı için GitHub'daki Android DAI örneklerine göz atın.