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ışı
- 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. - Kullanıcı, ara vermeden videoyu ileri sararsa
seekFrom
ileseekTo
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:
- 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;
}
}
});
BreakClip
,setBreakClipLoadInterceptor
geri çağırmada boş değer döndürerek atlanabilir.playerManager.getBreakManager().setBreakClipLoadInterceptor(breakClip => {
return null;
});