Reklam Araları

Genel bakış

Web Alıcısı SDK'sı, belirli bir medya akışındaki reklam araları ve tamamlayıcı reklamlar için yerel destek sunar. Alıcıya reklam araları eklemenin iki yolu vardır: molalar ve molalar kullanılarak istemci tarafı ve sunucu tarafı birleştirme.

Reklam aralarını geliştirmeye başlamadan önce Özel Web Alıcısı kurulumu hakkında bilgi edinin. Cast SDK Ad Breaks API, reklamlar oynatmanın bir parçası olduğunda kullanıcıların Cast uyumlu tüm cihazlarda tutarlı bir deneyim yaşamasını sağlar.

Bu kılavuzda ara, bir veya daha fazla reklam veya bumper içeren oynatma aralığını ifade eder. Her reklam veya bumper, ara klibi olarak adlandırılır.

Bu şemada, her biri iki reklam içeren iki reklam arası gösterilir:

Etkinlikler

Aşağıdaki tabloda, oynatma sırasında aralarla karşılaşıldığında tetiklenen etkinlikler açıklanmaktadır.

Etkinliği Ara	Açıklama
BREAK_STARTED	Bir aradaki ilk ara klibi yüklenmeye başladığında tetiklenir. Etkinlik cast.framework.events.BreaksEvent.
BREAK_ENDED	Aradaki son ara klibi sona erdiğinde tetiklenir. Etkinlik cast.framework.events.BreaksEvent. Not: Bu etkinlik, kullanıcı bir molada son mola klibi atlasa bile tetiklenir.
BREAK_CLIP_LOADING	Ara klibi yüklenmeye başladığında tetiklenir. Etkinlik cast.framework.events.BreaksEvent.
BREAK_CLIP_STARTED	Ara klibi başladığında tetiklenir. Etkinlik cast.framework.events.BreaksEvent.
BREAK_CLIP_ENDED	Ara klibi sona erdiğinde tetiklenir. Etkinlik, cast.framework.events.BreaksEvent. Not: Bu etkinlik, kullanıcı mola klibini atlasa bile tetiklenir. Lütfen BreaksEvent ile ilişkili endedReason özelliğini kontrol edin. Ara klibinin ne kadar süre izlendiğini öğrenmek için lütfen PlayerManager üzerinden getBreakClipCurrentTimeSec ve getBreakClipDurationSec videolarına göz atın.

Bu etkinlikler, analiz ve reklam oynatma izleme için kullanılabilir. VMAP (Video Çoklu Reklam Oynatma Listesi) ve VAST (Video Reklam Sunma Şablonu) kullanıldığında, yanıtlarda sağlanan tüm standart izleme etkinlikleri SDK tarafından otomatik olarak gönderilir.

Ara oynatılırken Web Alıcısı SDK'sı, tüm bağlı gönderenlere breakStatus ile MediaStatus yayınlar. Gönderenler, bu bilgileri kullanıcı arayüzlerini güncellemek ve arama işlemlerini kısıtlamak için kullanabilir.

Web Alıcısı SDK'sı, reklam aralarını alıcıya dahil etmek için iki yol sağlar: istemci tarafı ve sunucu tarafı birleştirme.

İstemci taraflı reklam birleştirme

İstemci taraflı reklam birleştirmede de yerleşik olmayan olarak da adlandırılır. Medya yüklenirken gerekli reklam bilgileri Break ve BreakClip nesneleriyle belirtilmelidir. Aşağıdaki snippet'te, videodan önce gösterilen reklam, videonun ortasında gösterilen reklam ve videodan sonra gösterilen reklam araları ekleme işlevine dair bir örnek verilmiştir. third_party ile ilgili referanslar ve yöntemleri, geliştiricilerin uygulamalarında kullanabilecekleri yardımcı işlevlere örnek olarak verilebilir. Bu snippet'te, kullanıcılar bir BREAK_CLIP_ENDED sonuna kadar dinlenen ve endedReason değerini kontrol ederek mola klibini izleyen izleme etkinliklerinin nasıl tetiklenebileceği de gösterilmektedir.

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.breakClips = [
  {
    id: 'bc1',
    title: third_party.getBreakClipTitle('bc1'),
    contentId: third_party.getBreakClipUrl('bc1'),
    contentType: third_party.getBreakClipContentType('bc1'),
    posterUrl: third_party.getBreakClipPosterUrl('bc1')
  },
  {
    id: 'bc2'
    ...
  },
  {
    id: 'bc3'
    ...
  },
  {
    id: 'bc4'
    ...
  }];
  mediaInformation.breaks = [
  {
    id: 'b1',
    breakClipIds: ['bc1', 'bc2'],
    position: 0  //pre-roll position
  },
  {
    id: 'b2',
    breakClipIds: ['bc3'],
    position: 10*60 //ten minutes
  },{
    id: 'b3',
    breakClipIds: ['bc4'],
    position: -1  //post-roll position (-1 is only valid client stitching; for server-side ad stitching, exact position is required)
  }];
}

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.addEventListener(cast.framework.events.EventType.BREAK_CLIP_ENDED, function(event){
  if(event.endedReason === cast.framework.events.EndedReason.END_OF_STREAM){
    //call your ad tracking code here for break clip watched to completion
  }
});


playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    loadRequestData => {
      addBreakToMedia(loadRequestData.media);
      return loadRequestData;
    });
context.start();

VAST Reklamları

Web Alıcısı SDK'sı, IAB standart VAST reklamlarını destekler. VAST reklamlarını medyanıza eklemek için bir vastAdsRequest nesnesi oluşturun ve bunu bir BreakClip vastAdsRequest özelliğine atayın. vastAdsRequest nesnesinde adsResponse özelliği veya adTagUrl özelliği tanımlı olmalıdır.

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.breakClips = [
  {
    id: 'bc1',
    vastAdsRequest:{
      adTagUrl: 'https://castsample.com/vast?rand=' + Math.floor(Math.random()* 10000)
    }
  }];
}

Web Alıcısı SDK'sı, belirtilen adTagUrl öğesine bir istek gönderir ve XML yanıtını ayrıştırarak bir BreakClip nesnesi oluşturur. SDK'mız tarafından oluşturulan bir BreakClip nesnesi örneği aşağıda verilmiştir.

{
  "id": "GENERATED:0",
  "contentId": "https://file.mp4",
  "contentType": "video/mp4",
  "title": "Preroll",
  "duration": 10,
  "clickThroughUrl": "https://click"
}

VMAP reklamları

Web Alıcı SDK'sı, IAB VMAP standardını da destekler. Bir VMAP sağlandığında Cast SDK, VMAP yanıtını ayrıştırır ve yanıttaki belirli <AdBreak> girişleri için Break koruma nesneleri oluşturur. Ayrıca VMAP'de sağlanan her <AdSource> girişi için bir vastAdsRequest nesnesiyle uygun BreakClips oluşturur. İçeriğinize reklam eklemek için VMAP'yi kullanmak istiyorsanız vastAdsRequest nesnesi oluşturun ve yükleme isteğinizin kapsamında MediaInformation nesnesinin vmapAdsRequest özelliğine atayın.

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.vmapAdsRequest = {
    adTagUrl: 'https://castsample.com/vmap?rand=' + Math.floor(Math.random()* 10000)
  };
}

Sunucu tarafı reklam birleştirme

Yerleşik reklamlar olarak da adlandırılan sunucu tarafı birleştirme için sunucunun hem birincil medyayı hem de reklamları içeren tek bir akış sağlaması beklenir. Bu durumda, geliştiricinin BreakClip için duration ve contentType özelliklerini sağlaması beklenir. contentUrl atlandı. Ayrıca, isEmbedded true olarak ayarlanmalıdır.

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.breakClips = [
  {
    id: 'bc1',
    title: third_party.getBreakClipTitle('bc1'),
    posterUrl: third_party.getBreakClipPosterUrl('bc1'),
    duration: third_party.getBreakClipDuration('bc1')
  },
  {
    id: 'bc2'
    ...
  },
  {
    id: 'bc3'
    ...
  },
  {
    id: 'bc4'
    ...
  }];
  mediaInformation.breaks = [
  {
    id: 'b1',
    breakClipIds: ['bc1', 'bc2'],
    position: 0,
    isEmbedded: true
  },
  {
    id: 'b2',
    breakClipIds: ['bc3', 'bc4'],
    position: 10*60,
    isEmbedded: true
  }];
}

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    loadRequestData => {
      addBreakToMedia(loadRequestData.media);
      return loadRequestData;
    });
context.start();

Molaların davranışı

Varsayılan ara davranışı

1. Bir ara başladığında, isWatched olarak işaretlenir. Kullanıcı daha önce aradan önce ara verdiğinde içerik normalde olduğu gibi oynatılmaya başlar ve ara daha önce izlendiği için atlanır.
2. Kullanıcı, ara vermeden videoyu ileri sararsa seekFrom ile seekTo konumu arasındaki son oynatılamayan içerik, içerik oynatılmaya başlamadan önce oynatılır.

Özel ara davranışı

Mola ve mola klipleri için default behavior, BreakManager nesnesindeki setBreakClipLoadInterceptor ve setBreakSeekInterceptor yöntemleri kullanılarak değiştirilebilir.

setBreakClipLoadInterceptor

setBreakClipLoadInterceptor, bir arayla karşılaşmadan önce çağrılır. Bu işlev her ara klibinde bir kez çağrılır. Geri çağırma işlevine bir BreakClip nesnesi aktarır.

Örneğin, bir videodan önce gösterilen reklam arası varsa setBreakClipLoadInterceptor, oynatma başlar başlamaz videodan önce gösterilen reklam arası için çağrılır. Videodan önce gösterilen reklam oynatıldıktan hemen sonra, bir sonraki ara için setBreakClipLoadInterceptor çağrılır.

setBreakClipLoadInterceptor işlevine geri çağırma işlevinde null veya herhangi bir şey döndürülmezse, kesme klibi atlanır. Mola veren tüm müdahaleler hemen çağrılır.

setBreakClipLoadInterceptor kullanılarak, BreakClip nesnesi oynatılmaya başlamadan önce değiştirilebilir.

setBreakSeekInterceptor

setBreakSeekInterceptor, bir arama işleminden sonra tetiklenir ve geri çağırma işlevine bir BreakSeekData nesnesi geçirir. BreakSeekData nesnesi, mevcut video oynatma zamanı ile arama zamanının arasına karşılık gelen konumlarının yer aldığı bir ara dizisi içerir (örneğin, seekFrom ve seekTo). İleri sarma işleminden sonra, varsayılan davranış seekTo zamanından önceki son oynatılmayan arayı oynatmaktır. Ara sona erdiğinde içerik oynatma seekTo konumundan devam eder.

Bu önleyici, ilgili aralardaki BreakClip nesnelerinin değiştirilmesine olanak tanır.

Davranışı özelleştirmek istiyorsanız default behavior öğesini geçersiz kılmak için setBreakSeekInterceptor uygulayabilirsiniz. setBreakSeekInterceptor uygulandıysa hangi araların oynanacağını açıkça belirtmeniz gerekir.

• setBreakSeekInterceptor öğesinden boş değer döndürülürse veya hiçbir sonuç döndürülmezse ara atlanır.
• Geri çağırma işlevine aktarılan nesne döndürülürse default behavior geçersiz kılınır ve tüm aralar oynatılır. Ayrıca, kullanıcı önceki bir noktayı ileri geri sararsa bu araları daha önce izlemiş olsa bile araları görür. setBreakSeekInterceptor uygulanmazsa daha önce izlenen aralar atlanır.

Ara klipleri atlanabilir yapma

Ara klibini atlanabilir yapmak için BreakClip nesnesinde ara klibi atlanmadan önce kaç saniye bekleneceğini belirtin.

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(media) {
  media.breakClips = [
  {
    id: 'bc1',
    ...
    whenSkippable: 10 //to allow user to skip break clip from sender after 10 seconds
  }];
}

Reklamları otomatik atla

Reklamlar, kullanıcı etkileşimi olmadan otomatik olarak atlanabilir. Reklamları atlamanın iki yolu vardır:

1. Bir Ara'nın isWatched özelliği doğru değerine ayarlanırsa ara otomatik olarak atlanır.

   playerManager.addEventListener(cast.framework.events.category.CORE, function(event){
     if(event.type === cast.framework.events.EventType.PLAYER_LOADING){
       let breaks = playerManager.getBreaks();
       for(let i in breaks){
         breaks[i].isWatched = true;
       }
     }
   });

2. BreakClip, setBreakClipLoadInterceptor geri çağırmada boş değer döndürerek atlanabilir.

   playerManager.getBreakManager().setBreakClipLoadInterceptor(breakClip => {
     return null;
   });