Reklam Araları

Genel bakış

Web Alıcı SDK'sı, belirli bir medya akışındaki reklam araları ve tamamlayıcı reklamlar için yerel destek sunar. Reklam konumunu, reklam kaynağını, reklam aralarının davranışını ve ilişkili ara kliplerini ayarlamak için API'ler sunar. Bu kılavuzda Break, bir veya daha fazla reklam ya da bumper içeren oynatma aralığını ifade eder. Her reklam veya bumper, BreakClip olarak adlandırılır. Bu aralar yüklenen veya oynatılan medyayla ilişkilidir.

Reklam türleri

Web Alıcı SDK'sı, istemci tarafı reklam eklemeyi (CSAI) ve sunucu tarafından birleştirilmiş reklam eklemeyi (SSAI) destekler. İstemci tarafından birleştirilmiş reklamlar, uygulama tarafından manuel olarak ayarlanabilir veya VAST ve VMAP şablon dosyalarından çıkarılabilir. Sunucu tarafından birleştirilmiş reklamlar, içerik yüklenmeden önce manuel olarak yerleşik reklam olarak veya içerik oynatma sırasında dinamik olarak yerleştirilmiş genişletilmiş reklamlar olarak belirtilmelidir. Bu reklam türlerinin her biri için uygulamalar aşağıda ayrıntılı olarak açıklanmıştır.

müşteri tarafından dikilmiş manuel

İstemci tarafından birleştirilmiş manuel reklam arası, istemci tarafından birbirine eklenen bir reklam arası türüdür. Bu reklam arası, SDK API'leri kullanılarak uygulama tarafından manuel olarak belirtilir. Bu reklam türü, ana içeriğin akışına yerleştirilmemiş. BreakClip, reklam içeriğine işaret eden URL olan contentId'i, reklam içeriğinin biçimini açıklayan contentType'ı ve title bilgisini sağlamalıdır.

Break öğesinde isEmbedded ve expanded false varsayılan değerine ayarlanmış olmalıdır. position videodan önce gösterilen reklam, videonun ortasında gösterilen reklam veya videodan sonra gösterilen reklam olarak ayarlanabilir (Daha fazla bilgi için ara konumlandırması bölümüne bakın). Web Alıcı SDK'sı, reklamı oynatmaya hazırlarken reklam içeriğini yüklemek ve oynatmak için başka bir oynatıcı örneği oluşturur. Bu aralar stitched timeline gerektirir ve statik olarak eklenmelidir (daha fazla bilgiyi reklam ekleme bölümünde bulabilirsiniz). Aşağıdaki örnekte, istemci kaynaklı manuel bir reklamın temel bir uygulaması gösterilmektedir:

// Create the BreakClip.
let clipClient = new cast.framework.messages.BreakClip('bc_client');
clipClient.title = 'The Ad Title to be displayed during playback';
clipClient.contentId = 'https://example.com/ad.m3u8';
clipClient.contentType = 'application/vnd.apple.mpegurl';

// Optional: Used when HLS ad container formats differ from the main content's.
clipClient.hlsSegmentFormat = cast.framework.messages.HlsSegmentFormat.FMP4;

// Create the Break using the BreakClip id above.
let breakPostrollClient = new cast.framework.messages.Break(
    'break_postroll_client', ['bc_client'], -1);
breakPostrollClient.isEmbedded = false; // Optional: default is false.
breakPostrollClient.expanded = false; // Optional: default is false.

VAST

Web Alıcı SDK'sı, IAB standart VAST (Video Reklam Sunma Şablonu) reklamlarının eklenmesini destekler. XML şablonu sağlandığında, ara girildikten sonra istemci tarafından eklenmiş bir ara klibi oluşturulacak şekilde ayrıştırılır.

VAST reklamı oluşturmak için alıcı uygulamanın bir VastAdsRequest oluşturması ve bunu BreakClip vastAdsRequest özelliğinde belirtmesi gerekir. VastAdsRequest nesnesi, adsResponse (XML şablonunun kendisinin dize gösterimi) veya adTagUrl (XML şablonunun barındırıldığı URL) özelliğinin tanımlanmış olması gerekir. URL belirtilmişse SDK, şablonu getirme işlemini gerçekleştirecektir. Kapsülleme Break, istemci tarafından birleştirilmiş reklam kurallarına uyar. Bu reklamlar, aynı içerikte müşteri tarafından birleştirilmiş diğer manuel reklamlarla birlikte veya aynı içerik için ayrı aralara eklenebilir. Aşağıdaki örnekte, bir VAST reklamının temel bir uygulaması gösterilmektedir:

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/ads.xml'

// Create the BreakClip.
let clipVast = new cast.framework.messages.BreakClip('bc_vast');
clipVast.vastAdsRequest = vastTemplate;

// Create the Break using the BreakClip id above.
let breakPostrollVast = new cast.framework.messages.Break(
    'break_postroll_vast', ['bc_vast'], -1);
breakPostrollVast.isEmbedded = false; // Optional: default is false.
breakPostrollVast.expanded = false; // Optional: default is false.

VAST BreakClip içeren bir Break girildiğinde Web Alıcı SDK'sı isteğe bağlı olarak şablonu getirir ve ayrıştırır. Ayrıştırma işlemi sırasında SDK, yeni bir BreakClip oluşturur ve bunu şablondan çıkarılan contentId, contentType, title, duration, whenSkippable ve clickThroughUrl gibi değerlerle doldurur. Oluşturulan ara klibinin id değeri GENERATED:N olarak ayarlanmıştır. Burada N, 0'dan itibaren oluşturulan her yeni VAST ara klibi için 1 oranında artan bir tam sayıdır. Oluşturulan reklam daha sonra BreakClip dizisine eklenir. Her VAST ara klibinin geçerli Break içindeki id'si, karşılık gelen oluşturulan ara klibinin id ile değiştirilir. Aşağıdaki snippet'lerde bu tür bir aradan önce ve sonra reklamlarla ilgili MEDIA_STATUS mesajlarında yapılan değişiklikler gösterilmektedir.

VAST reklamlarında ara girmeden önceki Break ve BreakClip bilgileri.

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "bc_vast"
    ],
    "position": 0,
    "isWatched": false
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  }
]

VAST reklamları ile ara girdikten sonra Break ve BreakClip bilgileri.

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "GENERATED:0"
    ],
    "position": 0,
    "isWatched": true
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  },
  {
    "id": "GENERATED:0",
    "contentId": "https://example.com/break-clip-1.mpd",
    "contentType": "application/dash+xml",
    "title": "Ad Title Extracted from Template",
    "duration": 10,
    "whenSkippable": 5,
    "clickThroughUrl": "https://example.com/ad-target"
  }
]

VMAP

Web Alıcı SDK'sı, IAB VMAP (Video Birden Çok Reklam Oynatma Listesi) standardını destekler. Bir VMAP sağlandığında Web Alıcı SDK'sı, VMAP yanıtını ayrıştırır ve yanıttaki tüm <AdBreak> girişleri için istemci tarafından birleştirilmiş Break nesneleri oluşturur. Ayrıca, VMAP'de sağlanan her <AdSource> girişi için bir vastAdsRequest nesnesiyle uygun BreakClips öğesini oluşturur. İçeriğinize reklam eklemek üzere VMAP'yi etkinleştirmek için uygulamanın bir VastAdsRequest nesnesi oluşturması ve bunu LoadRequestData içindeki MediaInformation öğesinin vmapAdsRequest özelliğine ataması gerekir. Bu reklamlar statik olarak eklenmelidir (daha fazla bilgi için reklam ekleme bölümünü inceleyin). Aşağıda bir VMAP isteğinin oluşturulmasını özetleyen bir snippet verilmiştir.

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/vmap.xml'

// Add it to the MediaInformation of the LoadRequest.
loadRequestData.media.vmapAdsRequest = vastTemplate;

yerleşik

Yerleştirilmiş reklam arası, sunucu tarafında ana içeriğin akışına birleştirilmiş bir reklam arası türüdür. Break süresi, medya süresi hesaplanırken ana içeriğin süresinden çıkarılır.

BreakClip, reklam içeriğinin duration ve title özelliklerini sağlamalıdır. Break için isEmbedded ayarı true, expanded ise false olarak ayarlanmalıdır. position, videodan önce gösterilen reklam veya videonun ortasında gösterilen reklam olarak ayarlanabilir. Videodan sonra gösterilen reklam reklam araları, pozitif tam position değerleriyle desteklenir. Bu konu hakkında daha fazla bilgiyi ara konumlandırma bölümünde bulabilirsiniz. Reklam oynatılması için tetiklendiğinde, Web Alıcı SDK'sı, reklam segmentleri içine yerleştirilmiş olarak akışı oynatmaya devam eder. Bu reklam türü için ek yükleme mekanizması yok. Video yer imleci ara zaman aralığına geldiğinde ilgili reklam meta verileri kullanıcıya gösterilir. Bu aralar embedded timeline gerektirir ve statik olarak eklenmelidir (daha fazla bilgiyi reklam ekleme bölümünde bulabilirsiniz). Aşağıdaki örnekte, embedded reklamının temel bir uygulaması gösterilmektedir.

// Create the BreakClip.
let clipEmbedded = new cast.framework.messages.BreakClip('bc_embedded');
clipEmbedded.title = 'The Ad Title to be displayed during playback';
clipEmbedded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbedded = new cast.framework.messages.Break(
    'break_preroll_embedded', ['bc_embedded'], 0);
breakPrerollEmbedded.isEmbedded = true;
breakPrerollEmbedded.expanded = false; // Optional: default is false.

yerleşik genişletildi

Yerleşik genişletilmiş reklam arası, sunucu tarafında ana içeriğin akışına birleştirilmiş bir reklam arası türüdür. Break süresi, medya süresi hesaplanırken ana içeriğin süresine dahil edilir.

BreakClip, reklam içeriğinin duration ve title özelliklerini sağlamalıdır. Break için isEmbedded ayarı true, expanded ise true olarak ayarlanmalıdır. position, videodan önce gösterilen reklam veya videonun ortasında gösterilen reklam olarak ayarlanabilir. Videodan sonra gösterilen reklam reklam araları, pozitif position değerleriyle desteklenir. Bu konu hakkında daha fazla bilgiyi ara konumlandırma bölümünde bulabilirsiniz. Reklam oynatılması için tetiklendiğinde, Web Alıcı SDK'sı, reklam segmentleri içine yerleştirilmiş olarak akışı oynatmaya devam eder. Bu reklam türü için ek yükleme mekanizması yok. Video yer imleci ara zaman aralığına geldiğinde ilgili reklam meta verileri kullanıcıya gösterilir. Bu aralar bir embedded timeline gerektirir ve statik olarak veya dinamik olarak eklenebilir (daha fazla bilgiyi reklam ekleme bölümünde bulabilirsiniz). Aşağıdaki örnekte, bir embedded expanded reklamının temel bir uygulaması gösterilmektedir:

// Create the BreakClip.
let clipEmbeddedExpanded =
    new cast.framework.messages.BreakClip('bc_embedded_expanded');
clipEmbeddedExpanded.title = 'The Ad Title to be displayed during playback';
clipEmbeddedExpanded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbeddedExpanded = new cast.framework.messages.Break(
    'break_preroll_embedded_expanded', ['bc_embedded_expanded'], 0);
breakPrerollEmbeddedExpanded.isEmbedded = true;
breakPrerollEmbeddedExpanded.expanded = true;

Oynatıcı zaman çizelgesi türleri

Web Alıcı SDK'sı, oynatıcı örneği oluştururken içerik oynatma sırasında reklam oynatmayı desteklemek için bir zaman çizelgesi türü seçer. Her zaman çizelgesi, belirli reklam arası türlerinin eklenmesini sağlar. Zaman çizelgesi türü, LoadRequestData öğesinin MediaInformation yükleme süresi sırasında mevcut olan reklam türlerine göre belirlenir. Yerleştirilmiş reklam araları mevcutsa embedded zaman çizelgesi seçilir. İstemci tarafından birleştirilmiş reklam araları varsa stitched zaman çizelgesi seçilir. Herhangi bir reklam olmadığında SDK varsayılan olarak embedded zaman çizelgesini kullanır. Zaman çizelgesi seçildikten sonra mevcut medya öğesi için değiştirilemez. Aşağıdaki tabloda her zaman çizelgesinin ayrıntılı açıklamaları yer almaktadır.

Zaman Çizelgesi Türü Açıklama
yerleştirilmiş zaman çizelgesi Ana içeriğe yerleştirilmiş reklamları (yerleştirilmiş ve yerleştirilmiş genişletilmiş reklam araları) destekleyen medya süresini temsil eder. Genişletilmemiş bir reklam arası varsa bu reklam arasının süresi, içeriğin toplam süresinden çıkarılır. Öte yandan, genişletilmiş bir reklam arası varsa bu reklam arasının zamanı ana içeriğin bir parçası olarak kabul edilir.
birleştirilmiş zaman çizelgesi Harici medya dosyalarından gelen reklamları destekleyen medya zamanını (istemci tarafından manuel olarak birleştirilmiş, VAST ve VMAP reklam araları). Eklendiğinde reklam arasının süresi, ana içeriğin süresinin bir parçası olmaz.

Aşağıdaki 1-3 numaralı şekillerde çeşitli reklam türleri içeren bazı içerikler ve bu içeriklerin zaman çizelgesi değerleri gösterilmektedir. İçerik, iki ara klip içeren bir videodan önce gösterilen reklam arası ile tek bir ara klibi içeren videonun ortasında gösterilen reklam ve videodan sonra gösterilen reklam aralarıyla yapılandırılır. İçerik oynatmanın başlangıcından itibaren geçen duvar saati, ana içeriğin medya zamanı ve aranın şu anda oynatılan ara klibinin zamanı her bir şeklin altında hizalanır.

Müşteri tarafından birleştirilmiş reklamların zaman çizelgesi
Şekil 1: Bazı içerikleri ve bu içeriklerin istemci tarafından eklenmiş 3 reklam aralarını temsil eden zaman çizelgesi.


Sunucu tarafından birleştirilmiş reklamların zaman çizelgesi
Şekil 2: Bazı içerikleri ve bu içeriklerin sunucu tarafından birleştirilmiş 3 reklam arasını temsil eden zaman çizelgesi.


Sunucu tarafından birleştirilmiş, genişletilmiş reklamların zaman çizelgesi
Şekil 3: Bazı içerikleri ve bu içeriklerin sunucu tarafından birleştirilmiş, genişletilmiş 3 reklam aralarını temsil eden zaman çizelgesi.

Ara konumlandırma

Web Receiver SDK'sı, geliştiricilerin Break öğesinin position özelliğini ayarlayarak reklam aralarının nereye yerleştirilmesi gerektiğini belirlemelerine olanak tanır. Bu değer, ana içeriğin medya zamanına karşılık gelir ve pre-roll, mid-roll ile post-roll reklam araları oluşturmak için kullanılabilir. Bunlar şu şekilde tanımlanır:

Kesme Konumu Açıklama
videodan önce gösterilen reklam Ana içerikten önce oynatılan bir reklam arası. Bu, breakPosition öğesinin 0 olarak ayarlanmasıyla gösterilir
videonun ortasında gösterilen reklam İçeriğin ortasında oynatılan bir reklam arası. Bu, breakPosition öğesinin aranın başlangıcının ana içeriğin başlangıcından daha uzun olduğu ve aranın bitiş zamanının ana içeriğin bitiş zamanından kısa olduğu bir zamana ayarlanmasıyla gösterilir.
videodan sonra gösterilen reklam Ana içerikten sonra oynatılan bir reklam arası. Bu, birleştirilmiş zaman çizelgeleri için breakPosition öğesinin -1 değerine ayarlanmasıyla belirtilir. Yerleştirilmiş zaman çizelgeleri için breakPosition, ana içeriğin süresinden aranın süresi çıkarılarak ayarlanmalıdır. Canlı içerik için desteklenmez.

Birlikte çalışabilirlik matrisi

Tablo 1'de, hızlı bir referans noktası olarak reklam türlerine ve bunların reklamla ilgili özelliklerle uyumluluklarına genel bir bakış sunulmaktadır.

Tablo 1: Reklamların birlikte çalışabilirlik matrisi
Özellik Desteği müşteri tarafından birleştirilmiş manuel reklam VAST VMAP yerleşik reklam yerleşik genişletilmiş reklam
şununla uyumlu: VAST müşteri tarafından dikilmiş manuel Yok yerleşik genişletildi yerleşik
zaman çizelgesi birleştirilmiş birleştirilmiş birleştirilmiş yerleşik yerleşik
reklam ekleme statik statik statik statik statik, dinamik
reklam kaldırma
videodan önce gösterilen reklam
videonun ortasında gösterilen reklam
videodan sonra gösterilen reklam
reklam atlama
ara ara önleyici
kesme klibi yük önleyici

Etkinlikler

Önemli ara etkinlikleri gerçekleştiğinde Yayın SDK'sı, BreaksEvent türündeki etkinlikleri gönderir. Alıcı uygulama, PlayerManager addEventListener API'sini kullanarak bunlara abone olabilir.

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

Etkinlik türleri, ne zaman tetiklendikleriyle ilgili ayrıntılı bir açıklamayla birlikte Tablo 2'de listelenir.

Ara Etkinlikleri Yaşam Döngüsü
Şekil 4: Ara etkinlikleri yaşam döngüsü.
Tablo 2: Ara etkinlikleri ve açıklamaları.
Ara Etkinliği Açıklama
BREAK_STARTED Ana içeriğin geçerli medya süresi, izlenmemiş bir aranın position değerine eşit olduğunda tetiklenir.
BREAK_CLIP_LOADING Yalnızca, birleştirilmiş zaman çizelgesi bir ara klibi yüklenmeye başladığında tetiklenir.
BREAK_CLIP_STARTED Bir ara klibi oynatmaya başladığında tetiklenir.
BREAK_CLIP_ENDED Bir ara klibi sona erdiğinde tetiklenir. endedReason alanı şu koşullar için doldurulur:
  • Tamamen oynatılan, birleşik bir zaman çizelgesindeki ara klibi.
  • Birleştirilmiş zaman çizelgesindeki ara klibi, başka bir ara klibine geçiyor.
  • Ara klipleri atlanır.
  • Son ara klibi, videodan sonra gösterilen reklam yerleştirilmiş arada tamamen oynatılır.
  • Bir hata oluştu.
BREAK_ENDED Aradaki son ara klibi sona erdiğinde tetiklenir.

Reklam ekleme

Yayın SDK'sı, uygulamaların yayın oturumunun farklı anlarında reklam ekleyip kaldırmasını sağlar. İki tür reklam ekleme vardır: statik ve dinamik. Statik reklam ekleme için oynatıcı oluşturulmadan önce reklamların LoadRequestData içinde belirtilmesi gerekir. Dinamik reklam ekleme, önceden yüklenmiş içeriğe ara eklemek için BreakManager addBreak API'den yararlanır. Her ekleme yöntemi türü, belirli reklam türleriyle uyumludur. Birlikte çalışabilirlik matrisinde uyumluluğa genel bakış sağlanmıştır.

Statik reklam ekleme

Statik reklam ekleme, oynatıcı oluşturmadan önce ilgili reklam meta verilerinin eklenmesiyle tanımlanır. Bu bilgiler LoadRequestData hükümlerinin MediaInformation bölümünde sağlanmıştır. Örneğin bu, bağlı bir gönderenin orijinal yükleme isteğinde ayarlanabilir veya LOAD isteğine müdahale edilerek Web Alıcısı uygulaması tarafından eklenebilir. LoadRequestData, işlenmek üzere Web Alıcı SDK'sına döndürüldükten sonra oynatıcı oluşturulur. Medyaları yükleme hakkında daha fazla bilgi edinin. Aşağıdaki örnekte, LOAD istek engelleyiciye eklenen ve istemci tarafından birleştirilmiş bir reklam gösterilmektedir.

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

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {

  // Create the BreakClip.
  let clipClient = new cast.framework.messages.BreakClip('bc_client');
  clipClient.title = 'The Ad Title to be displayed during playback';
  clipClient.contentId = 'https://example.com/ad.mp4';
  clipClient.contentType = 'video/mp4';

  // Create the Break using the BreakClip id above.
  let breakPostrollClient = new cast.framework.messages.Break(
      'break_postroll_client', ['bc_client'], -1);

  // Set the ad information in the load request data.
  let media = loadRequestData.media;
  media.breakClips = [clipClient];
  media.breaks = [breakPostrollClient];

  return loadRequestData;
});

Dinamik reklam ekleme

Dinamik reklam ekleme, içerik oynatma sırasında reklam arası ayarlanmasıyla tanımlanır. Bu işlem, BreakManager örneğinin alınması ve addBreak API'sinin çağrılmasıyla gerçekleştirilir. Bu işlem için en az iki parametre gerekir: yerleşik bir genişletilmiş Break ve bir BreakClip dizisi. true olarak ayarlandığında değişikliklerin bir MediaStatus yayını aracılığıyla bağlı gönderenlere gönderilmesini zorunlu kılmak için isteğe bağlı bir üçüncü özellik eklenir. Ara ve ara klipleri eklerken karşılık gelen kimlikler benzersiz olmalıdır. Bu reklamlar, yalnızca oynatıcı oluşturulduktan sonra eklenebilir. Web Buyer SDK'sı, oynatıcı oluşturulduğunda PLAYER_LOADING etkinliğini tetikler. Bir akışın ID3 meta verilerindeki değişikliklere yanıt veren ve zaman çizelgesine eklemek için Break ve BreakClip nesneleri oluşturan bir etkinlik işleyicide kullanımı gösteren aşağıdaki örneğe bakın.

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

playerManager.addEventListener(cast.framework.events.EventType.ID3, (event) => {

  // Create the BreakClip.
  let clipEmbeddedExpanded = parseBreakClipFromData(event.segmentData);
  let breakEmbeddedExpanded = parseExpandedBreakFromData(event.segmentData);

  // Add the break and break clip.
  breakManager.addBreak(breakEmbeddedExpanded, [clipEmbeddedExpanded]);
});

Dinamik reklam kaldırma

Dinamik araları kaldırmak için uygulamanın oynatma sırasında removeBreakById araması yapması gerekir. İşlev, zaman çizelgesinden kaldırılacak aranın dize tanımlayıcısını alır. Belirtilen breakId, yerleştirilmiş genişletilmiş bir reklam arasına işaret etmelidir. Başka türde bir reklam arası algılanırsa ara, zaman çizelgesinde kalır. Aşağıdaki, arayı kaldıran örneğe bakın.

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

breakManager.removeBreakById('break_midroll_embedded_expanded');

Araların davranışı

SDK, oynatıcının mola girip ayrıldığı durumlar için varsayılan bir davranış tanımlar ve BreakManager'da sağlanan bazı API'leri kullanarak oynatıcıyı daha fazla özelleştirmenin bir yolunu sunar.

Varsayılan ara davranışı

Normal oynatma veya bir Break üzerinden arama yapılarak Break girildiğinde SDK, kullanıcının isWatched özelliğini kontrol ederek bu öğeyi daha önce görüp görmediğini değerlendirir. Oluşturulduğunda bu mülk için bir aranın varsayılan değeri false olur. Özellik true ise girildiğinde ara çalınmaz ve ana içerik oynatılmaya devam eder. Özellik false ise ara girildiğinde oynatılır.

Geçmiş araları ararken varsayılan uygulama, position değeri arama işleminin seekFrom ve seekTo değerleri arasında olan tüm Break öğelerini alır. SDK, bu aralar listesinde position değeri seekTo değerine en yakın ve isWatched özelliği false olarak ayarlanmış Break öğesini oynatır. Bu aranın isWatched özelliği true olarak ayarlanır ve oynatıcı mola kliplerini oynatmaya başlar. Ara izlendiğinde, ana içerik seekTo konumundan oynatmaya devam eder. Böyle bir ara yoksa ara çalınmaz ve ana içerik seekTo konumunda oynatılmaya devam eder.

Ara oynatma sırasında SDK, MediaStatus içindeki bağlı gönderen uygulamalarıyla ilgili tüm güncellemeleri yayınlar. Bu uygulamalar, yayınları kullanarak breakStatus özelliğini okuyarak reklamlar için kullanıcı arayüzünü günceller. Bu özellik yalnızca ara oynatma sırasında tanımlanır.

Alıcı uygulamaları ayrıca PlayerManager getBreakClipCurrentTimeSec çağrısıyla gösterilen BreakClip'ın geçerli zamanına göre video yer imlecinin konumuyla ilgili bilgileri doğrudan sorgulayabilir. Benzer şekilde, uygulamalar getBreakClipDurationSec yöntemini çağırarak mevcut BreakClip öğesinin süresini sorgulayabilir.

Özel ara davranışı

Aralar ve ara klipleriyle ilgili varsayılan davranış, BreakManager ürününde sağlanan setBreakClipLoadInterceptor ve setBreakSeekInterceptor yöntemleri kullanılarak değiştirilebilir.

Kırılmayı aralama önleyicisi

Ara bulma önleyici, uygulamanın reklam aralarını arama davranışını kontrol etmesine olanak tanır. Bir veya daha fazla ara üzerinden ileriye ya da geriye doğru arama yapan bir arama işlemi istendiğinde işlev tetiklenir. BreakSeekData çağrıldığında, geri çağırma işlevine parametre olarak iletilir. BreakSeekData nesnesi, position özelliği seekFrom olarak tanımlanan video yer imleci ile arama hedef zamanı seekTo arasındaki bir sayıya ayarlanmış bir Break nesne dizisi içerir.

Bu önleyici, ilgili aralardaki Break nesnelerinin değiştirilmesine olanak tanır. Uygulandığında, ara bulma önleyicisi isteğe bağlı olarak değiştirilmiş bir BreakSeekData nesnesi döndürerek hangi reklam aralarının oynatılacağını belirtmelidir. Oynatıcı, döndürülen değere dahil edilen tüm araları oynatır. null değeri veya mola arama önleyicisinden hiçbir şey döndürülmezse ara atlanır.

Önceden izlenen aralar haricinde, tüm reklam aralarını izlemek için varsayılan davranışı geçersiz kılan basit bir ön aracı uygulaması için aşağıdaki örneğe bakın.

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

breakManager.setBreakSeekInterceptor((breakSeekData) => {

  // Filter the breaks array by removing watched breaks.
  const unwatchedBreaks =
      breakSeekData.breaks.filter(adBreak => !adBreak.isWatched);
  breakSeekData.breaks = unwatchedBreaks;

  return breakSeekData;
});

Klip yükü kesiciyi kırma

Ara klibi yük önleyici kullanılarak, bir BreakClip nesnesi oynatılmaya başlamadan önce değiştirilebilir.

Ara klibi yük engelleyici, yalnızca birleştirilmiş zaman çizelgesi araları için çağrılır ve setBreakClipLoadInterceptor ile ayarlanabilir. Break girmeden önce bu önleyici, bu arada tanımlanan her bağımsız BreakClip için bir kez çağrılır. SDK, geri çağırma işlevinin parametresi olarak orijinal BreakClip nesnesini iletir. Uygulama daha sonra bu BreakClip öğesini değiştirip döndürerek SDK'nın, ara klibini güncellenmiş yapılandırmayla getirip görüntüleyebilmesini sağlayabilir. null döndürülürse veya hiçbir şey döndürülürse ara klibi atlanır.

Ara kliplerinin contentUrl değerini, getUrlFromClipId yardımcı program işleviyle değiştiren bir örneği aşağıda görebilirsiniz. Burada, BreakClip öğesinin id öğesi bir URL ile eşlenir.

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

breakManager.setBreakClipLoadInterceptor(
    (breakClip, breakClipLoadInterceptorContext) => {

  // Obtains the URL of a break clip id from a function call.
  breakClip.contentUrl = getUrlFromClipId(breakClip.id);

  return breakClip;
});

Reklam Atlama

Web Receiver SDK'sı, bir reklam arası içindeki reklam aralarını ve ayrı ara klipleri atlamak için API'ler sağlar. SDK, kullanıcıların gönderen uygulamalarıyla veya akıllı ekran cihazlarıyla etkileşim kurarak isteğe bağlı olarak ara klipleri atlamasına da olanak tanır.

Kullanıcı tarafından atlanabilir ara klipleri

Ara kliplerini atlanabilir olarak ayarlamak, kullanıcıların bağlı gönderici uygulamalarıyla ve akıllı ekran cihazlarıyla etkileşimde bulunup o anda oynatılan ara klibinin geri kalanını isteğe bağlı olarak atlamasına olanak tanır. whenSkippable özelliğini negatif olmayan bir saniye sayısına ayarlamak, bu özelliği BreakClip nesnesi için etkinleştirir. Oynatıcı, ara klibi belirtilen saniye boyunca oynatıldıktan sonra ara klibini atlanabilir olarak kabul eder. Bu değerin 0 olarak ayarlanması, kullanıcıların ara klibini hemen atlamasına olanak tanır.

// Create the BreakClip.
let clip = new cast.framework.messages.BreakClip('bc');
clip.title = 'The Ad Title to be displayed during playback';
clip.whenSkippable = 10; // Users can skip the clip after 10 seconds of playback.

Bu bilgiler, gönderenin orijinal yükleme isteğinde veya alıcı uygulamasında ayarlanabilir. Atlandığında, birleştirilmiş zaman çizelgesi reklam arasındaki ara klibi, geçerli ara klibini oynatmayı durdurur. Oynatıcı, varsa bir sonraki ara klibini veya ana içeriği yükler. Atlandığında, yerleştirilmiş zaman çizelgesi reklam arasındaki ara klibi, ara klibinin sonuna doğru ilerler ve bu noktada akışı oynatmaya devam eder.

Reklamları programatik olarak atlama

Ayrıca reklamlar kullanıcı etkileşimi olmadan otomatik olarak atlanabilir.

Bir uygulama, aranın tamamını atlamak için Break özelliğinin isWatched özelliğini true olarak ayarlamalıdır. Bu, yükleme sırası veya içerik oynatma sırasında herhangi bir zamanda yapılabilir. isWatched özelliği, ana içeriğin şu anki zamanında bir aranın position değerine ulaşıldığında oynatıcı tarafından değerlendirilir. Bu noktada, ara verilip girilmeyeceğini oyuncu belirler. Tüm araları döngüye alan ve oynatıcı yüklenirken değeri değiştiren örneği aşağıda görebilirsiniz.

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

playerManager.addEventListener(cast.framework.events.EventType.PLAYER_LOADING,
    (event) => {

  // Obtain the breaks and iterate through each item to skip all ad breaks.
  let breaks = breakManager.getBreaks();
  breaks.forEach((brk) => {
    brk.isWatched = true;
  });
});

Belirli bir ara klibini programatik olarak atlamak için kırılma klibi yükü önleyici kullanılmalıdır. null döndürüldüğünde veya geri çağırma işlevinde bir değer döndürülmediğinde bu aradaki klip atlanır.

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

breakManager.setBreakClipLoadInterceptor(
      (breakClip, breakClipLoadInterceptorContext) => {
  return null;
});