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

ExoPlayer, kullanıcılara Android için uygulama düzeyinde medya oynatıcı. Bu kılavuz, ExoPlayer IMA uzantısı, içeren bir medya akışı isteği göndermek ve oynatmak için IMA DAI SDK'sını sarmalayan hem reklam hem de içerik.

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. Buradan özet:

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

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

Bu kılavuz, ExoPlayer ile rehber ve programlar tam uygulama oluşturmayı ve uzantıyı entegre etmeyi öğreneceğiz. Bkz. ExoPlayerExample, kalkış: GitHub'ı tam bir örnek uygulama.

Önemli Nokta: ExoPlayer IMA uzantısı ExoPlayer'a bağlıdır. Dilerseniz farklı bir oynatıcı kullanmak için rehberini inceleyin.

Ön koşullar

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

Yeni Android Studio projesi oluştur

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 projenizi adlandırın ve şunun için Java'yı seçin: dilini girin.

  Not: IMA DAI SDK'sı Kotlin ile uyumludur. Ancak, örnekteki Java'yı kullanmaktadır.

• Son'u tıklayın.

ExoPlayer IMA uzantısını projenize ekleme

Uygulama düzeyindeki build.gradle dosyasına uzantı için içe aktarmalar ekleyin (dependencies bölümünde).

Uygulamanızı yapılandırarak multidex. Bu işlem, uzantının boyutuna dahildir ve minSdkVersion ayarı olan uygulamalar için gereklidir Android 4.4W (API düzeyi) sürümüne 20) veya daha düşük.

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 isteğinde bulunmak için IMA DAI SDK'sı tarafından gereken 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>

Amaç bildirimleri ekleyin

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

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

  <?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 şu şekilde değiştirin: LinearLayout (ExoPlayer IMA uzantısı için önerilir).

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 ekleyin

IMA örnek akışını inceleyin örnek akış için öğeler de kullanabilirsiniz. Ayrıca Ad Manager bölümüne bakın Kurulum hakkında bilgi için DAI otomatik olarak oluşturun.

Bu adım, bir canlı yayın oluşturmayı gösterir ancak ExoPlayer IMA'sı uzantısı, DAI VOD akışlarını da destekler. Talebe bağlı video (VOD) hizmeti adımına bakın. canlı yayınlar başlıklı makalemizi incelemenizi öneririz.

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

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

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

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

Bununla test etmek için Big Buck Bunny (Canlı) HLS akışının öğe anahtarını ekleyin akış şeklinde gösterilir. Test edebileceğiniz daha fazla yayın var IMA'nın örnek akış sayfası.

AdsLoader değerini kaydedip almak için bir KEY_ADS_LOADER_STATE sabit değeri oluşturun durumu.

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şturun

PlayerView öğesini bulmak ve kayıtlı bir öğe olup olmadığını kontrol etmek için onCreate yönteminin üzerine yazın AdsLoader.State, Bu değer, adsLoader nesnesini başlatırken kullanılabilir.

Ayrıca, uygulamanızın yöntem sayısı ve minSdkVersion nedeniyle gerekiyorsa multidex'i etkinleştirin (bkz. 2. Adım).

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şlatmak için yöntemler ekleyin

Oynatıcıyı başlatmak için bir yöntem ekleyin ve 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 değerini oynatıcınıza ayarlayın.

Not: Bu bölümde, sunucu tarafı reklama referans veren adlara sahip yöntemler kullanılmaktadır. kavramlarını inceleyeceğiz.

• Google Ad Manager DAI 'nı inceleyin. SSAI'nin bir örneğidir.
• Bu kılavuzun ExoPlayer IMA uzantısı uygulaması, özellikle de Ad Manager DAI ile. ExoPlayer IMA uzantıları da Google Cloud Platform gibi diğer SSAI örneklerini destekler. görebilirsiniz.

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 ekleyin

Oynatıcıyı bu dizide 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 öğesinin 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, akışı işlemek amacıyla etkinliğin yaşam döngüsü etkinlikleri için geri çağırmalar oluşturun oynatmaya devam edebilirsiniz.

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

• onStart()
• onStop()

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

onStart() ve onResume(), playerView.onResume(), onStop() ve ile eşleşiyor playerView.onPause() için onPause() haritası.

Önemli Bilgi: Bu örnekte hem Android SDK 24+ 24'ten düşük sürümler. Android SDK 24 ve sonraki sürümleri için onStart()/onStop() uygulamasını kullanın desteği ve 24'ün altındaki sürümler için onResume()/onPause() desteği sunulur.

Bu adımda ayrıca onSaveInstanceState() etkinliğini kullanın.adsLoaderState

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 reklam içeren VOD içerik oynatması gerekiyorsa şunları yapmanız gerekir: şu:

1. VOD test akışı için CMS ID ve Video ID ekleyin.
2. ImaServerSideAdInsertionUriBuilder() işlevini 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 = "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. Şu anda ExoPlayer ile medya akışı istiyor ve oynatıyorsunuz IMA uzantısı kullanabilirsiniz. Şu konulardaki Android DAI örneklerine göz atın: GitHub'ı ziyaret edin.