Reklam ekleme

ExoPlayer, hem istemci tarafı hem de sunucu tarafı reklam ekleme için kullanılabilir.

İstemci tarafı reklam ekleme

İstemci tarafı reklam eklemede oynatıcı, içerik ve reklam oynatma arasında geçiş yaparken farklı URL'lerden medya yükleme arasında geçiş yapar. Reklamlarla ilgili bilgiler, medyadan ayrı olarak (ör. XML VAST veya VMAP reklam etiketinden) yüklenir. Bu bilgiler arasında, içeriğin başlangıcına göre reklam işaret konumları, gerçek reklam medya URI'leri ve belirli bir reklamın atlanabilir olup olmadığı gibi meta veriler yer alabilir.

İstemci tarafı reklam ekleme için ExoPlayer'ın AdsMediaSource özelliğini kullanırken oynatıcı, oynatılacak reklamlar hakkında bilgiye sahip olur. Bu durumun çeşitli avantajları vardır:

• Oynatıcı, API'sini kullanarak reklamlarla ilgili meta verileri ve işlevleri gösterebilir.
• ExoPlayer kullanıcı arayüzü bileşenleri, reklam konumları için işaretçileri otomatik olarak gösterebilir ve reklamın oynatılıp oynatılmadığına bağlı olarak davranışlarını değiştirebilir.
• Oynatıcı, reklamlar ve içerik arasındaki geçişlerde dahili olarak tutarlı bir arabellek sağlayabilir.

Bu kurulumda oynatıcı, reklamlar ve içerik arasında geçiş yapma işlemini gerçekleştirir. Bu sayede uygulamaların, reklamlar ve içerik için birden fazla ayrı arka plan ve ön plan oynatıcısını kontrol etmesi gerekmez.

İçerik videoları ve reklam etiketleri istemci tarafı reklam ekleme ile kullanılmak üzere hazırlanırken reklamlar, oynatıcının içerik oynatmayı sorunsuz bir şekilde devam ettirebilmesi için ideal olarak içerik videosundaki senkronizasyon örneklerine (ana kareler) yerleştirilmelidir.

Bildirimsel reklam desteği

MediaItem oluşturulurken bir reklam etiketi URI'si belirtilebilir:

val mediaItem =
  MediaItem.Builder()
    .setUri(videoUri)
    .setAdsConfiguration(MediaItem.AdsConfiguration.Builder(adTagUri).build())
    .build()
AdInsertion.kt

MediaItem mediaItem =
    new MediaItem.Builder()
        .setUri(videoUri)
        .setAdsConfiguration(new MediaItem.AdsConfiguration.Builder(adTagUri).build())
        .build();
AdInsertion.java

Reklam etiketlerini belirten medya öğeleri için oynatıcı desteğini etkinleştirmek üzere oynatıcıyı oluştururken AdsLoader.Provider ve AdViewProvider ile yapılandırılmış bir DefaultMediaSourceFactory oluşturup eklemeniz gerekir:

val mediaSourceFactory: MediaSource.Factory =
  DefaultMediaSourceFactory(context)
    .setLocalAdInsertionComponents(adsLoaderProvider, playerView)
val player = ExoPlayer.Builder(context).setMediaSourceFactory(mediaSourceFactory).build()
AdInsertion.kt

MediaSource.Factory mediaSourceFactory =
    new DefaultMediaSourceFactory(context)
        .setLocalAdInsertionComponents(adsLoaderProvider, /* adViewProvider= */ playerView);
ExoPlayer player =
    new ExoPlayer.Builder(context).setMediaSourceFactory(mediaSourceFactory).build();
AdInsertion.java

Dahili olarak DefaultMediaSourceFactory, içerik medya kaynağını bir AdsMediaSource içine sarmalar. AdsMediaSource, AdsLoader.Provider üzerinden bir AdsLoader alır ve bunu, medya öğesinin reklam etiketinde tanımlandığı şekilde reklam eklemek için kullanır.

ExoPlayer'ın PlayerView sınıfı, AdViewProvider arayüzünü uygular. ExoPlayer IMA kitaplığı, aşağıda açıklandığı gibi bir AdsLoader sağlar.

Reklamlı şarkı listeleri

Birden fazla medya öğesi içeren bir oynatma listesi oynatılırken varsayılan davranış, her medya kimliği, içerik URI'si ve reklam etiketi URI'si kombinasyonu için reklam etiketini bir kez istemek ve reklam oynatma durumunu bir kez depolamaktır. Bu, reklam etiketi URI'leri eşleşse bile kullanıcıların, reklam içeren her medya öğesi için farklı bir medya kimliği veya içerik URI'si olan reklamlar göreceği anlamına gelir. Bir medya öğesi tekrarlanırsa kullanıcı ilgili reklamları yalnızca bir kez görür (reklam oynatma durumu, reklamların oynatılıp oynatılmadığını depolar, böylece ilk kez oynatıldıktan sonra atlanır).

Belirli bir medya öğesinin reklam oynatma durumunun nesne eşitliğine göre bağlandığı opak bir reklam tanımlayıcısı ileterek bu davranışı özelleştirmek mümkündür. Aşağıda, reklam etiketi URI'sinin reklam tanımlayıcısı olarak iletilmesiyle reklam oynatma durumunun medya kimliği ve reklam etiketi URI'sinin kombinasyonu yerine yalnızca reklam etiketi URI'sine bağlandığı bir örnek verilmiştir. Bunun sonucunda reklamlar yalnızca bir kez yüklenir ve kullanıcı, oynatma listesini baştan sona oynatırken ikinci öğede reklam görmez.

// Build the media items, passing the same ads identifier for both items,
// which means they share ad playback state so ads play only once.
val firstItem =
  MediaItem.Builder()
    .setUri(firstVideoUri)
    .setAdsConfiguration(
      MediaItem.AdsConfiguration.Builder(adTagUri).setAdsId(adTagUri).build()
    )
    .build()
val secondItem =
  MediaItem.Builder()
    .setUri(secondVideoUri)
    .setAdsConfiguration(
      MediaItem.AdsConfiguration.Builder(adTagUri).setAdsId(adTagUri).build()
    )
    .build()
player.addMediaItem(firstItem)
player.addMediaItem(secondItem)
AdInsertion.kt

// Build the media items, passing the same ads identifier for both items,
// which means they share ad playback state so ads play only once.
MediaItem firstItem =
    new MediaItem.Builder()
        .setUri(firstVideoUri)
        .setAdsConfiguration(
            new MediaItem.AdsConfiguration.Builder(adTagUri).setAdsId(adTagUri).build())
        .build();
MediaItem secondItem =
    new MediaItem.Builder()
        .setUri(secondVideoUri)
        .setAdsConfiguration(
            new MediaItem.AdsConfiguration.Builder(adTagUri).setAdsId(adTagUri).build())
        .build();
player.addMediaItem(firstItem);
player.addMediaItem(secondItem);
AdInsertion.java

Sunucu destekli istemci tarafı reklam ekleme

ExoPlayer, HLS oynatma listesinde tanımlanan reklamların istemci tarafında otomatik olarak eklenmesini destekleyen HlsInterstitialsAdsLoader ile birlikte sunulur. HLS sayfasındaki HlsInterstitialsAdsLoader ile ilgili bölüme bakın.

ExoPlayer IMA kitaplığı

ExoPlayer IMA kitaplığı, istemci tarafı reklam ekleme özelliğini uygulamanıza entegre etmek için ImaAdsLoader sağlar. VAST/VMAP reklamlarının eklenmesini desteklemek için istemci tarafı IMA SDK'sının işlevini sarmalar. Arka planda oynatma ve oynatmayı devam ettirme gibi işlemler de dahil olmak üzere kitaplığın nasıl kullanılacağına dair talimatlar için README dosyasına bakın.

Demo uygulama, IMA kitaplığını kullanır ve örnek listesinde birkaç örnek VAST/VMAP reklam etiketi içerir.

Kullanıcı arayüzüyle ilgili dikkat edilmesi gereken noktalar

PlayerView, reklamların oynatılması sırasında taşıma kontrollerini varsayılan olarak gizler ancak uygulamalar, setControllerHideDuringAds yöntemini çağırarak bu davranışı değiştirebilir. IMA SDK, reklam oynatılırken oynatıcının üstünde ek görünümler gösterir (örneğin, "daha fazla bilgi" bağlantısı ve varsa atla düğmesi).

IMA SDK, reklamların oynatıcının üzerinde oluşturulan uygulama tarafından sağlanan görünümlerle engellenip engellenmediğini bildirebilir. Oynatmayı kontrol etmek için gerekli olan görünümleri yerleştirmesi gereken uygulamalar, görüntülenebilirlik hesaplamalarından çıkarılabilmeleri için bunları IMA SDK'ya kaydetmelidir. PlayerView, AdViewProvider olarak kullanıldığında kontrol yer paylaşımlarını otomatik olarak kaydeder. Özel oynatıcı kullanıcı arayüzü kullanan uygulamalar, yer paylaşımı görünümlerini AdViewProvider.getAdOverlayInfos üzerinden döndürerek kaydetmelidir.

Yer paylaşımlı görünümler hakkında daha fazla bilgi için IMA SDK'da Open Measurement başlıklı makaleyi inceleyin.

Tamamlayıcı reklamlar

Bazı reklam etiketleri, uygulama kullanıcı arayüzündeki "alanlarda" gösterilebilecek ek tamamlayıcı reklamlar içerir. Bu alanlar ImaAdsLoader.Builder.setCompanionAdSlots(slots) kullanılarak iletilebilir. Daha fazla bilgi için Tamamlayıcı reklam ekleme başlıklı makaleyi inceleyin.

Bağımsız reklamlar

IMA SDK, reklamları medya içeriğine eklemek için tasarlanmıştır, bağımsız reklamları tek başına oynatmak için değildir. Bu nedenle, bağımsız reklamların oynatılması IMA kitaplığı tarafından desteklenmez. Bu kullanım alanı için Google Mobile Ads SDK'sını kullanmanızı öneririz.

Üçüncü taraf reklam SDK'sı kullanma

Reklamları üçüncü taraf reklam SDK'sı kullanarak yüklemeniz gerekiyorsa ExoPlayer entegrasyonu sağlayıp sağlamadığını kontrol etmeniz önerilir. Aksi takdirde, üçüncü taraf reklam SDK'sını sarmalayan özel bir AdsLoader uygulamak, daha önce açıklanan AdsMediaSource avantajlarını sağladığı için önerilen yaklaşımdır. ImaAdsLoader, örnek bir uygulama olarak kullanılabilir.

Alternatif olarak, reklam ve içerik kliplerinden oluşan bir sıra oluşturmak için ExoPlayer'ın oynatma listesi desteğini kullanabilirsiniz:

// A pre-roll ad.
val preRollAd = MediaItem.fromUri(preRollAdUri)
// The start of the content.
val contentStart =
  MediaItem.Builder()
    .setUri(contentUri)
    .setClippingConfiguration(
      MediaItem.ClippingConfiguration.Builder().setEndPositionMs(120000).build()
    )
    .build()
// A mid-roll ad.
val midRollAd = MediaItem.fromUri(midRollAdUri)
// The rest of the content
val contentEnd =
  MediaItem.Builder()
    .setUri(contentUri)
    .setClippingConfiguration(
      MediaItem.ClippingConfiguration.Builder().setStartPositionMs(120000).build()
    )
    .build()

// Build the playlist.
player.addMediaItem(preRollAd)
player.addMediaItem(contentStart)
player.addMediaItem(midRollAd)
player.addMediaItem(contentEnd)
AdInsertion.kt

// A pre-roll ad.
MediaItem preRollAd = MediaItem.fromUri(preRollAdUri);
// The start of the content.
MediaItem contentStart =
    new MediaItem.Builder()
        .setUri(contentUri)
        .setClippingConfiguration(
            new MediaItem.ClippingConfiguration.Builder().setEndPositionMs(120_000).build())
        .build();
// A mid-roll ad.
MediaItem midRollAd = MediaItem.fromUri(midRollAdUri);
// The rest of the content
MediaItem contentEnd =
    new MediaItem.Builder()
        .setUri(contentUri)
        .setClippingConfiguration(
            new MediaItem.ClippingConfiguration.Builder().setStartPositionMs(120_000).build())
        .build();

// Build the playlist.
player.addMediaItem(preRollAd);
player.addMediaItem(contentStart);
player.addMediaItem(midRollAd);
player.addMediaItem(contentEnd);
AdInsertion.java

Sunucu tarafı reklam ekleme

Sunucu tarafı reklam eklemede (dinamik reklam ekleme veya DAI olarak da bilinir) medya akışı hem reklamları hem de içeriği içerir. DASH manifesti, muhtemelen ayrı dönemlerde hem içerik hem de reklam segmentlerini işaret edebilir. HLS için reklamları oynatma listesine ekleme ile ilgili Apple belgelerine bakın.

Sunucu tarafı reklam ekleme kullanılırken istemcinin, birleştirilmiş akışı almak için medya URL'sini dinamik olarak çözmesi, kullanıcı arayüzünde reklam yer paylaşımlarını göstermesi veya etkinlikleri bir reklam SDK'sına ya da reklam sunucusuna bildirmesi gerekebilir.

ExoPlayer'ın DefaultMediaSourceFactory sınıfı, ssai:// şemasını kullanan URI'ler için tüm bu görevleri sunucu tarafı reklam ekleme MediaSource sınıfına devredebilir:

val player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(
      DefaultMediaSourceFactory(context).setServerSideAdInsertionMediaSourceFactory(ssaiFactory)
    )
    .build()
AdInsertion.kt

Player player =
    new ExoPlayer.Builder(context)
        .setMediaSourceFactory(
            new DefaultMediaSourceFactory(context)
                .setServerSideAdInsertionMediaSourceFactory(ssaiFactory))
        .build();
AdInsertion.java

ExoPlayer IMA kitaplığı

ExoPlayer IMA kitaplığı, uygulamanızda IMA'nın sunucu tarafında eklenen reklam akışlarıyla entegrasyon için ImaServerSideAdInsertionMediaSource sağlar. Android için IMA DAI SDK'sının işlevlerini sarmalar ve sağlanan reklam meta verilerini oynatıcıya tam olarak entegre eder. Örneğin, bu sayede Player.isPlayingAd() gibi yöntemleri kullanabilir, içerik-reklam geçişlerini dinleyebilir ve oynatıcının, daha önce oynatılan reklamları atlama gibi reklam oynatma mantığını işlemesini sağlayabilirsiniz.

Bu sınıfı kullanmak için ImaServerSideAdInsertionMediaSource.AdsLoader ve ImaServerSideAdInsertionMediaSource.Factory öğelerini ayarlamanız ve bunları oynatıcıya bağlamanız gerekir:

// MediaSource.Factory to load the actual media stream.
val defaultMediaSourceFactory = DefaultMediaSourceFactory(context)
// AdsLoader that can be reused for multiple playbacks.
val adsLoader =
  ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(context, adViewProvider).build()
// MediaSource.Factory to create the ad sources for the current player.
val adsMediaSourceFactory =
  ImaServerSideAdInsertionMediaSource.Factory(adsLoader, defaultMediaSourceFactory)
// Configure DefaultMediaSourceFactory to create both IMA DAI sources and
// regular media sources. If you just play IMA DAI streams, you can also use
// adsMediaSourceFactory directly.
defaultMediaSourceFactory.setServerSideAdInsertionMediaSourceFactory(adsMediaSourceFactory)
// Set the MediaSource.Factory on the Player.
val player = ExoPlayer.Builder(context).setMediaSourceFactory(defaultMediaSourceFactory).build()
// Set the player on the AdsLoader
adsLoader.setPlayer(player)
AdInsertion.kt

// MediaSource.Factory to load the actual media stream.
DefaultMediaSourceFactory defaultMediaSourceFactory = new DefaultMediaSourceFactory(context);
// AdsLoader that can be reused for multiple playbacks.
ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader =
    new ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(context, adViewProvider).build();
// MediaSource.Factory to create the ad sources for the current player.
ImaServerSideAdInsertionMediaSource.Factory adsMediaSourceFactory =
    new ImaServerSideAdInsertionMediaSource.Factory(adsLoader, defaultMediaSourceFactory);
// Configure DefaultMediaSourceFactory to create both IMA DAI sources and
// regular media sources. If you just play IMA DAI streams, you can also use
// adsMediaSourceFactory directly.
defaultMediaSourceFactory.setServerSideAdInsertionMediaSourceFactory(adsMediaSourceFactory);
// Set the MediaSource.Factory on the Player.
Player player =
    new ExoPlayer.Builder(context).setMediaSourceFactory(defaultMediaSourceFactory).build();
// Set the player on the AdsLoader
adsLoader.setPlayer(player);
AdInsertion.java

ImaServerSideAdInsertionUriBuilder ile bir URL oluşturarak IMA öğe anahtarınızı veya içerik kaynağı kimliğinizi ve video kimliğinizi yükleyin:

val ssaiUri =
  ImaServerSideAdInsertionUriBuilder()
    .setAssetKey(assetKey)
    .setFormat(C.CONTENT_TYPE_HLS)
    .build()
player.setMediaItem(MediaItem.fromUri(ssaiUri))
AdInsertion.kt

Uri ssaiUri =
    new ImaServerSideAdInsertionUriBuilder()
        .setAssetKey(assetKey)
        .setFormat(C.CONTENT_TYPE_HLS)
        .build();
player.setMediaItem(MediaItem.fromUri(ssaiUri));
AdInsertion.java

Son olarak, artık kullanılmadığında reklam yükleyicinizi serbest bırakın:

adsLoader.release()
AdInsertion.kt

adsLoader.release();
AdInsertion.java

Kullanıcı arayüzüyle ilgili dikkat edilmesi gereken noktalar

İstemci tarafı reklam ekleme için geçerli olan kullanıcı arayüzüyle ilgili hususlar, sunucu tarafı reklam ekleme için de geçerlidir.

Tamamlayıcı reklamlar

Bazı reklam etiketleri, uygulama kullanıcı arayüzündeki "alanlarda" gösterilebilecek ek tamamlayıcı reklamlar içerir. Bu alanlar ImaServerSideAdInsertionMediaSource.AdsLoader.Builder.setCompanionAdSlots(slots) kullanılarak iletilebilir. Daha fazla bilgi için Tamamlayıcı Reklamlar Ekleme başlıklı makaleyi inceleyin.

Üçüncü taraf reklam SDK'sı kullanma

Reklamları üçüncü taraf reklam SDK'sı kullanarak yüklemeniz gerekiyorsa ExoPlayer entegrasyonu sağlayıp sağlamadığını kontrol etmeniz önerilir. Aksi takdirde, ImaServerSideAdInsertionMediaSource ile benzer şekilde ssai:// şemasıyla URI'leri kabul eden özel bir MediaSource sağlamanız önerilir.

Reklam yapısını oluşturmanın asıl mantığı, bir akışı MediaSource sarmalayan ve kullanıcının reklam meta verilerini temsil eden AdPlaybackState değerini ayarlayıp güncellemesine olanak tanıyan genel amaçlı ServerSideAdInsertionMediaSource öğesine devredilebilir.

Sunucu tarafında eklenen reklam akışları genellikle oynatıcıyı reklam meta verileri hakkında bilgilendirmek için zamanlanmış etkinlikler içerir. ExoPlayer tarafından desteklenen zamanlanmış meta veri biçimleri hakkında bilgi edinmek için desteklenen biçimler bölümüne bakın. Özel reklam SDK'sı MediaSource uygulamaları, Player.Listener.onMetadata kullanarak oynatıcıdan gelen zamanlanmış meta veri etkinliklerini dinleyebilir.