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

ExoPlayer, Android medya oynatıcısıdır. Bu kılavuzda, ExoPlayer IMA uzantısının nasıl kullanılacağı gösterilmektedir. Bu uzantı, hem reklam hem de içerik içeren medya akışlarını istemek ve oynatmak için IMA DAI SDK'sını kullanır.

Uzantının avantajları aşağıda listelenmiştir:

• IMA özelliklerini entegre etmek için gereken kodu basitleştirir.
• Yeni IMA sürümlerine güncelleme yapmak için gereken süreyi kısaltır.

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

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

ExoPlayer-IMA 1.1.0 ve sonraki sürümleri, DASH canlı yayınlarını destekler.

Bu kılavuz, tam bir uygulama oluşturmanıza ve uzantıyı entegre etmenize yardımcı olmak için ExoPlayer kılavuzunu kullanır. Tam bir örnek uygulama için GitHub'daki ExoPlayerExample bölümüne bakın.

Önemli Nokta: ExoPlayer IMA uzantısı için ExoPlayer gerekir. Farklı bir oynatıcı kullanmayı tercih ediyorsanız IMA DAI SDK'yı 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 sürüm 1.0.0 veya sonraki sürümler.

Yeni bir Android Studio projesi oluşturma

Android Studio projenizi oluşturmak için şu adımları uygulayın:

1. Android Studio'yu başlatın.
2. Yeni bir Android Studio projesi başlat'ı seçin.
3. Projenizi seçin sayfasında Etkinlik Yok şablonunu seçin.
4. İleri'yi tıklayın.
5. Projenizi yapılandırın sayfasında projenizi adlandırın ve dil olarak Java'yı seçin. Not: IMA DAI SDK, Kotlin ile çalışır ancak bu kılavuzda Java örnekleri kullanılmaktadır.

• Son'u tıklayın.

Projenize ExoPlayer IMA uzantısını ekleyin

ExoPlayer IMA uzantısını eklemek için aşağıdakileri yapın:

1. Uygulamanızın dependencies dosyasının build.gradle bölümüne aşağıdaki içe aktarmaları ekleyin:

   dependencies {
       def media3_version = "1.8.0"
       implementation(platform("org.jetbrains.kotlin:kotlin-bom:1.8.0"))
       implementation 'androidx.appcompat:appcompat:1.7.1'
       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"
   
       // The library adds the IMA ExoPlayer integration for ads.
       implementation "androidx.media3:media3-exoplayer-ima:$media3_version"
   }
   build.gradle
   

2. IMA DAI SDK'nın reklam isteğinde bulunmak için ihtiyaç duyduğu kullanıcı izinlerini ekleyin:

   <uses-permission android:name="android.permission.INTERNET"/>
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
   AndroidManifest.xml
   

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

ExoPlayer kullanıcı arayüzünü ayarlamak için aşağıdakileri yapın:

1. ExoPlayer için PlayerView nesnesini oluşturun.

2. ExoPlayer IMA uzantısının önerdiği gibi androidx.constraintlayout.widget.ConstraintLayout görünümünü LinearLayout görünümüne değiştirin:

   <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
       xmlns:tools="http://schemas.android.com/tools"
       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:fitsSystemWindows="true"
           android:layout_width="match_parent"
           android:layout_height="wrap_content" />
   
       <!-- UI element for viewing SDK event log -->
       <TextView
           android:id="@+id/logText"
           android:gravity="bottom"
           android:layout_width="match_parent"
           android:layout_height="wrap_content"
           android:maxLines="100"
           android:scrollbars="vertical"
           android:textSize="@dimen/font_size">
       </TextView>
   
   </LinearLayout>
   activity_my.xml
   

Akış parametrelerinizi ekleme

Projenizi test etmek için örnek yayın öğelerini IMA örnek yayın sayfasında bulabilirsiniz. Kendi akışlarınızı oluşturmak için DAI ile ilgili Ad Manager bölümüne bakın.

Bu adımda canlı yayın oluşturulur. ExoPlayer IMA uzantısı, DAI VOD yayınlarını da destekler. Uygulamanızın VOD yayınları için hangi değişikliklere ihtiyacı olduğunu öğrenmek istiyorsanız seç-izle video (VOD) yayınlarıyla ilgili adımı inceleyin.

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

1. ExoPlayer uzantısı için aşağıdaki içe aktarma ifadelerini ekleyin:

   import static androidx.media3.common.C.CONTENT_TYPE_HLS;
   
   import android.annotation.SuppressLint;
   import android.app.Activity;
   import android.net.Uri;
   import android.os.Bundle;
   import android.text.method.ScrollingMovementMethod;
   import android.util.Log;
   import android.widget.TextView;
   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.ui.PlayerView;
   import com.google.ads.interactivemedia.v3.api.AdEvent;
   import com.google.ads.interactivemedia.v3.api.ImaSdkFactory;
   import com.google.ads.interactivemedia.v3.api.ImaSdkSettings;
   import java.util.HashMap;
   import java.util.Map;
   MyActivity.java
   

2. MyActivity.java bölümüne şu özel değişkenleri ekleyin:

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

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

3. Durumu KEY_ADS_LOADER_STATEkaydetmek ve almak için bir sabit oluşturunAdsLoader:

   /** Main Activity. */
   @SuppressLint("UnsafeOptInUsageError")
   /* @SuppressLint is needed for new media3 APIs. */
   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 LOG_TAG = "ImaExoPlayerExample";
   
     private PlayerView playerView;
     private TextView logText;
     private ExoPlayer player;
     private ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader;
     private ImaServerSideAdInsertionMediaSource.AdsLoader.State adsLoaderState;
     private ImaSdkSettings imaSdkSettings;
   MyActivity.java
   

adsLoader örneği oluşturma

onCreate yöntemini geçersiz kılın. Bu bölümde PlayerView simgesini bulun ve AdsLoader.State simgesinin kaydedilmiş olup olmadığını kontrol edin. adsLoader nesnesini başlatırken bu durumu kullanabilirsiniz.

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

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

private ImaSdkSettings getImaSdkSettings() {
  if (imaSdkSettings == null) {
    imaSdkSettings = ImaSdkFactory.getInstance().createImaSdkSettings();
    // Set any IMA SDK settings here.
  }
  return imaSdkSettings;
}
MyActivity.java

Önemli: IMA yükleme sürelerini iyileştirmek için �ImaSdkFactory.initialize() yöntemini uygulama yaşam döngüsünde mümkün olduğunca erken çağırın. Yöntemin erken çağrılması, IMA'nın ilk yayın isteğinden önce gerekli kaynakları yüklemesi için ayrılan süreyi 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 rehberine göz atın.

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

Oynatıcıyı başlatmak için bir yöntem ekleyin. Bu yöntem şunları yapmalıdır:

• AdsLoader örneği oluşturun.
• ExoPlayer oluşturun.
• Canlı yayının öğe anahtarını kullanarak MediaItem oluşturun.
• Oynatıcınız için MediaItem ayarlayın.

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

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

  return adsLoaderBuilder
      .setAdEventListener(buildAdEventListener())
      .setImaSdkSettings(getImaSdkSettings())
      .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 a SimpleExoPlayer and set it as the player for content and ads.
  player = new ExoPlayer.Builder(this).setMediaSourceFactory(mediaSourceFactory).build();
  playerView.setPlayer(player);
  adsLoader.setPlayer(player);

  // Create the MediaItem to play, specifying the stream URI.
  Uri ssaiUri = buildLiveStreamUri(SAMPLE_ASSET_KEY, CONTENT_TYPE_HLS);
  MediaItem ssaiMediaItem = MediaItem.fromUri(ssaiUri);

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

/**
 * Builds an IMA SSAI live stream URI for the given asset key and format.
 *
 * @param assetKey The asset key of the live stream.
 * @param format The format of the live stream request, either {@code CONTENT_TYPE_HLS} or {@code
 *     CONTENT_TYPE_DASH}.
 * @return The URI of the live stream.
 */
public Uri buildLiveStreamUri(String assetKey, int format) {
  Map<String, String> adTagParams = new HashMap<String, String>();
  // Update the adTagParams map with any parameters.
  // For more information, see https://support.google.com/admanager/answer/7320899

  return new ImaServerSideAdInsertionUriBuilder()
      .setAssetKey(assetKey)
      .setFormat(format)
      .setAdTagParameters(adTagParams)
      .build();
}
MyActivity.java

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

• Google Ad Manager DAI SSAI örneğidir.
• Bu kılavuzdaki ExoPlayer IMA uzantısı özellikle Ad Manager DAI ile çalışır. ExoPlayer IMA uzantısı, farklı SSAI çözümlerini de destekler.

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

Oynatıcıyı serbest bırakmak için bir yöntem ekleyin. Bu yöntem, aşağıdaki işlemleri sırayla gerçekleştirmelidir:

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

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

Oynatıcı etkinliklerini işleme

Oyuncu etkinliklerini işlemek için yayının oynatılmasını yönetmek üzere etkinliğin yaşam döngüsü etkinlikleri için geri çağırmalar oluşturun.

Android API düzeyi 24 ve sonraki sürümlerde aşağıdaki yöntemleri kullanın:

• onStart()
• onStop()

Android API düzeyi 24'ten önceki sürümlerde aşağıdaki yöntemleri kullanın:

• onResume()
• onPause()

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

Önemli nokta: Bu örnek, Android SDK'nın 24. sürümünü ve önceki sürümlerini destekler. Android SDK sürümü 24 ve sonraki sürümler için onStart()/onStop(), 24'ten önceki sürümler için ise onResume()/onPause() kullanın.

Bu adımda, adsLoaderState değerini kaydetmek için onSaveInstanceState() etkinliği de kullanılır.

@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());
  }
}
MyActivity.java

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

Uygulamanızın reklam içeren VOD içeriği oynatması gerekiyorsa aşağıdaki adımları uygulayın:

1. VOD akışı için CMS ID ve Video ID ekleyin. Test için şu yayın parametrelerini kullanın:
   • CMS kimliği: "2548831"
   • Video kimliği: "tears-of-steel"

2. ImaServerSideAdInsertionUriBuilder() yöntemini kullanarak bir SSAI VOD URI'si oluşturun:

   /**
    * Builds an IMA SSAI VOD stream URI for the given CMS ID, video ID, and format.
    *
    * @param cmsId The CMS ID of the VOD stream.
    * @param videoId The video ID of the VOD stream.
    * @param format The format of the VOD stream request, either {@code CONTENT_TYPE_HLS} or {@code
    *     CONTENT_TYPE_DASH}.
    * @return The URI of the VOD stream.
    */
   public Uri buildVodStreamUri(String cmsId, String videoId, int format) {
     Map<String, String> adTagParams = new HashMap<String, String>();
     // Update the adTagParams map with any parameters.
     // For more information, see https://support.google.com/admanager/answer/7320899
   
     return new ImaServerSideAdInsertionUriBuilder()
         .setContentSourceId(cmsId)
         .setVideoId(videoId)
         .setFormat(format)
         .setAdTagParameters(adTagParams)
         .build();
   }
   MyActivity.java
   

3. MediaItem.fromUri() yöntemini kullanarak yeni VOD akışı URI'sini oynatıcınızın medya öğesi olarak ayarlayın.

İşlem başarılı olursa ExoPlayer IMA uzantısıyla bir medya akışı isteyebilir ve oynatabilirsiniz. Tam örnek için GitHub'daki Android DAI örneklerine bakın.