Video durumu bilgilerinin aktarımı

Video aramasının daha iyi çalışmasını sağlamak ve daha alakalı videolar göstermek için, videonun durumunu izlemeye yardımcı olan olaylar (örneğin, başlama zamanı, bitiş zamanı, video geri sarma zamanı, vb.) ve olası hatalar hakkında bilgi aktarmak gerekir.

Video durumunu bildiren olaylar

Video durumu bilgilerinin aktarımı için postMessage mekanizmasını kullanın. Oynatıcıda bir olay meydana geldiğinde (örneğin, bir video oynatılmaya başladığında), JavaScript kodunuzda window.parent.postMessage fonksiyonunu çağırın. Olay adını ve parametrelerini (örneğin, ilerleme çubuğunun konumu) fonksiyonun argümanı olarak iletin.

Fonksiyonun kullanımına dair örnek
window.parent.postMessage({
    event: <İşlem adı>,
    // ek işlem parametreleri
}, '*');

Not

postMessage fonksiyonu, videonun Yandex arama sonuçları ana sayfasında değil, ayrı bir çerçevede (iframe öğesinde) görüntülenmesidir nedeniyle, üst nesne window.parent için çağrılır.

Oynatıcının, TV için video arama uygulamasında ve tarayıcıda görüntülenmesi için zorunlu işlemlerin ve bunların parametrelerinin aktarılması gerekir.

Ek olayların aktarılması, oynatıcıyla etkileşimi iyileştirecek ve sinyaller videoları daha etkili bir şekilde sıralamaya yardımcı olacaktır.

İşlem

Açıklama

İşlem parametreleri

inited

Oynatıcının başlatılması.

–

paused

Videonun durdurulması.

time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.

ended

Videonun sona ermesi (sonuna kadar oynatılması).

time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.

started

Videonun başlatılması veya durdurulduktan sonra oynatmaya devam edilmesi.

  • time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.

    Time parametresi belirtilmediği durumlarda değeri varsayılan olarak 0 olur.

  • duration: Saniye cinsiden toplam video süresi Saniyeler yuvarlanmayabilir.

  • muted: Sesin kapalı olduğunun gösterir ve 0 veya 1 değerlerini alabilir.

  • quality: Video kalitesi (olası değerler: small, medium, large, hd720, hd1080, highres, 4K veya default).

timeupdate

Videonun oynatılması (defalarca tekralanan bir gelişme).

  • time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.

  • duration: Saniye cinsiden toplam video süresi Saniyeler yuvarlanmayabilir.

    <video> öğesindeki timeupdate yerel işlemine benzerdir.

error

Oynatma hatası, video kullanılamıyor.

  • time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.

  • code: Hata kodu.

  • message: Hata türü hakkında bilgi içeren mesaj.

adShown

Reklam gösteriminin başlatılması.

  • count: Mevcut reklam bloğunda gösterilecek reklam videolarının sayısı.

  • time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.

  • ads: Reklam videoları listesi verilerini içeren bir dizi. Her bir video için, ilgili dizide parametreler olması gerekir:

    • duration: Saniye cinsinden toplam reklam süresi. Saniyeler yuvarlanmayabilir.

    • skip: Reklamı atlamak mümkündür (arayüzde bununla ilgili bir bildirim görüntülenir) ve 0 veya 1 değerlerini alabilir.

adShown işlemi için veri örnekleri
1. Örnek

Reklam bloğu videonun otuzuncu saniyesinde oynatma işlemine başlıyor ve iki reklam içeriyorsa, ayrıca bunlardan ilki 15 saniye uzunluğunda ve atlanabilir, ikincisi ise 25 saniye uzunluğunda ve atlanamazsa, adShown işleminde aşağıdaki veriler bulunmalıdır:

{
  count: 2,
  time: 30,
  ads: [{
      duration: 15.0,
      skip: 1
    },{
      duration: 25.3,
      skip: 0
    }
  ]
}
2. Örnek

Blok, videonun en başında oynatılan tek bir reklam içeriyor (preroll), 45 saniye sürüyor ve ileri sarılamıyorsa:

{
  count: 1,
  time: 0,
  ads: [{
      duration: 45.5,
      skip: 0
    }
  ]
}

Not

Reklam parametrelerini içeren bilgiler ayrı bir beforeAdStart işlemi olarak gönderilebilir.

adEnd

Reklam gösteriminin sonu.

time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.

contentImpression

Videonun ilk karesinin gösterimi.

Not

Video başlamadan önce bir reklam oynatılırsa, reklam bittikten sonra videonun ilk karesi göründüğünde olayı gönderin.

time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.

İşlem

Açıklama

İşlem parametreleri

rewound

Videonun sarılması.

  • time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.

  • previousTime: İlerleme çubuğunun önceki durumu (sn.).

resumed

Oynatmanın yeniden başlatılması.

  • time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.

  • duration: Saniye cinsiden toplam video süresi Saniyeler yuvarlanmayabilir.

  • muted: Sesin kapalı olduğunun gösterir ve 0 veya 1 değerlerini alabilir.

  • quality: Video kalitesi (olası değerler: small, medium, large, hd720, hd1080, highres, 4K veya default).

Not

resumed işlemi zorunlu started işlemi ile değiştirilebilir.

volumechange

Sesin açılması, kapatılması veya seviyesinin değiştirilmesi.

<video> öğesinin volumechange yerel işlemi ile aynıdır.

bufferingStarted

Videonun bütünüyle veya kısmen önbelleğe alınma işleminin başlaması.

  • size: Yüklenen bayt miktarı.

  • time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.

  • quality: Video kalitesi (olası değerler: small, medium, large, hd720, hd1080, highres, 4K veya default).

bufferingEnded

Videonun bir kısmının yüklenmesinin sonu.
  • time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.
  • quality: Video kalitesi (olası değerler: small, medium, large, hd720, hd1080, highres, 4K veya default).

adSkip

Reklamın atlanması, adEnd yerine geçmez.

–

adSkippable

Bir reklamın skipAd metodu kullanılarak atlanabileceğini belirten olay.
  • time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.

qualityList

Mevcut video kalitesi değerleri listesi.

list: Videonun kalite değerlerinin listesi (olası değerler: 144, 240, 360, 480, 720, 1080, 1440, 2160).

qualityChange

Video kalitesini değiştirme.

  • quality: Video kalitesi (olası değerler: small, medium, large, hd720, hd1080, highres, 4K veya default).

  • time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.

playbackRateChange

Oynatma hızını değiştirme.

  • time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.

  • rate: Hızlanma/yavaşlama katsayısı.

fullscreen

Oynatıcının tam ekran moduna geçişi veya tam ekran modundan çıkışı.

enabled: Etkinleştirilmiş veya değil.

playerReady

Oynatıcı yüklendi ve kullanılmaya hazır (veriler ve oynatıcı API'si yüklendi).

–

playbackRateChanged

Video oynatma hızını değiştirme.

  • rate: Oynatma hızı 0..1.

  • time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.

controlsHidden

Oynatıcı kontrol öğelerinin programlı olarak gizlenmesi özelliği (hideControls yöntemi ile, geçici gizleme değil).

time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.

controlsShown

Oynatıcı kontrol öğelerinin gösterilme işareti (showControls yönteminin çağrılmasına yanıt olarak, geçici gösterim değil).

time: İlerleme çubuğunun saniye cinsinden mevcut pozisyonu.

clickout

Reklama, servise geçiş için oynatıcıdan dış kaynağa çıkış.

  • source: Geçiş türü. Geçerli değerler:

    • adv: Reklama geçiş (reklama tıklama).

    • related: Oynatıcı içindeki video bloğundan başka bir videoya geçiş.

    • self: Logoya tıklayarak servisteki aynı videoya geçiş.

    • unknown: Başka bir geçiş.

  • url: Geçtiğiniz sayfanın adresi.

sourceUpdated

Bu işlem, çerçeve (iframe öğesi) içindeki herhangi bir videonun yerine başka bir video koyulması durumunda gönderilmelidir. Örneğin, oynatıcı, API aracılığıyla, oynatıcıyı yeniden oluşturma gereği olmadan videoyu değiştirmeye izin veriyorsa, bu işlem videonun yerine başka bir video koyulduğunu belirtir.

  • id: Video kimliği.

  • params: Videonun diğer tüm parametreleri.

fullscreenError

Tam ekran moduna girerken veya çıkarken bir hata oluştu.

message: Hata mesajı.

qualityList

Mevcut video kalitesi değerleri listesi.

list: Olası değerler: small, medium, large, hd720, hd1080, highres, 4K veya default.
Bir video başlatıldığında bilgilerin nasıl aktarıldığı örneği

Kullanıcı oynatıcının Play butonuna tıkladığında, window.parent.postMessage işlevi gerekli parametrelerle çağrılır.

// Video başlatıldığında ileti gönderimi
window.parent.postMessage({
  event: 'started',
  duration: 30,
  time: 5 // Videonun 5. saniyeden sonra yeniden oynatılması halinde
}, '*');

Hata bilgileri

Video oynatılması sırasında ortaya çıkan hatalarla ilgili bilgi almak için oynatıcı window.parent.postMessage işlevine aşağıda sıralanan hata kodlarını iletmelidir:

Hata kodu

Açıklama

Videoya erişilemiyor

101

Video kaldırıldı.

102

Video veya kullanıcı hesabı engellendi.

103

Video mevcut değil veya URL desteklenmiyor.

100

Videoya erişilemeyen diğer durumlar.

Videoya erişim sınırlı

151

Videoyu izlemek için yetkiniz yok.

152

Videonun başka sitelerde oynatılması yasak.

153

Videonun bu bölgede oynatılması yasak.

154

Kullanıcıdan onay gerektiren erişim kısıtlaması (örneğin, yaş sınırlamaları, servise giriş yapma).

155

Servis, sorgunun bot tarafından yapıldığını değerlendirdiği için kullanılamıyor.

156

Videoya yalnızca abonelikle erişilebilir.

150

Videonun izlenmesini engelleyen diğer kısıtlamalar.

Diğerleri

5

Oynatıcı hatası (ör., HTML oynatıcısının çalışmasında ortaya çıkan hatalar).

0

Diğer hatalar.
Hata mesajı gönderme örneği

Oynatıcıda açılan video silinmişse, hata mesajı şu şekilde gönderilebilir:

// Hata mesajının gönderilmesi
window.parent.postMessage({
  event: 'error',
  time: 0,
  code: '101'
}, '*');

Oynatıcının URL'inde parametrelerin desteklenmesi

Smart TV ve tarayıcıda video oynatmanın kullanıcılar için daha rahat olması için, oynatıcının URL'sine aşağıdaki parametrelerin desteğini ekleyin:

Parametre

Açıklama

Geçerli değerler

autoplay

Videonun otomatik oynatılması.

  • 1: Video otomatik olarak oynat.

  • 0 (veya seçenek yoksa): Video otomatik olarak oynatma.

Örnek
<iframe 
  src="//www.videohosting.com/video?autoplay=1">
</iframe>

tv

Smart TV'lerde etkileşimli oynatıcı öğelerinin yönetimi.

  • 1: Video oynatılırken etkileşimli öğeleri otomatik olarak gizle.

  • 0 (veya parametre yoksa): Video oynatılırken etkileşimli öğeleri otomatik olarak gizleme.

Örnek
<iframe
  src="//www.videohosting.com/video?tv=1">
</iframe>

Parametre, sadece fare imleciyle tıklanabilen tüm öğelerin görüntülenmesini yönetir. Aşağıdakiler bu gruptandır:

  • ilerleme çubuğu;

  • sezon ve bölümlerin açılır listeleri;

  • oynatma kalitesi seçenekleri butonları;

  • oynatma kontrol menüsü, vb.

Bu öğeler otomatik gizlenerek video daha rahat izlenebilir.

mute

Videoyu, sesi kapalı olarak yükle.

  • 1: Kullanıcı, sesi kendisi etkinleştirene kadar videonun sesini etkinleştirme.

  • 0 (veya parametre belirtilmemesi): Sesin oynatıcıdaki davranışı, barındırma servisinin takdirine bağlıdır. İstenirse video sesli olarak başlatılabilir.

controls

Oynatıcıda kontrol öğelerini (ilerleme çubuğu, kalite değiştirme vb.) göstermek gerekiyor mu?

  • 1 (veya parametrenin belirtilmemesi): Oynatıcı için kontrol öğelerinin tümünü göster.

  • 0: Oynatıcı için kontrol öğelerini gösterme.

t

Videonun oynatılmaya başlatılması gereken zaman etiketi.

[number]: Saniye cinsinden.

Örnek

Örnekte video 10.00'da (600 sn = 10 dk) oynatılmaya başlayacaktır.

<iframe
  src="//www.videohosting.com/video?t=600">
</iframe>

Oynatıcıyı yönetme

Kontrol komutları oynatıcı tarafından iframe'e postMessage mekanizması kullanılarak dış pencereden gönderilir. iframe içindeki iletileri almak için message işlemine abone olun. Komutlar, zorunlu method alanını içeren JSON objeleridir.

Komut

Açıklama

play

Videonun başlatılması veya devam ettirilmesi.

Örnek
{
    method: 'play'
}

pause

Videonun durdurulması.

Örnek
{
    method: 'pause'
}

seek

Videonun mutlak zaman olarak sarılması.

Örnek
{
     method: 'seek',
     time: 10, // saniye olarak zaman
}

setVolume

Sesin ayarlanması.

Örnek
{
     method: 'setVolume',
     volume: 0.5 // ses düzeyi 0..1
}

showControls

Oynatıcı kontrol öğelerinin zorla gösterilmesi.

Örnek
{
    method: 'showControls'
}

skipAd

Reklam atlama yöntemi.

Örnek
{
     method: 'skipAd',
}

setPlaybackRate

Video oynatma hızını ayarlama.

Örnek
{
     method: 'setPlaybackRate',
     rate: 0.5 // oynatma hızı  0..1
}

mute

Sesin kapatılması.

Örnek
{
     method: 'mute'
}

unmute

Sesin açılması.

Örnek
{
     method: 'unmute'
}

setQuality

Oynatma kalitesi ayarları.

Örnek
{
     method: 'setQuality',
     quality: '720' // 144, 240, 360, 480, 720, 1080, 1440, 2160 veya auto
}

Auto parametresi, oyuncunun bağımsız olarak en uygun kaliteyi belirlemesine olanak tanır. Bağlantı hızına ve kullanıcının cihaz parametrelerine bağlı olarak varsayılan değeri kullanabilir veya en uygun kaliteyi seçebilir.

updateSource

Video oynatıcısında, tüm iframe'i yeniden çizmeden videonun yerine başka video koyma yöntemi.

params: Bir sonraki videonun yüklenmesi için parametreler.

Örnek
{
  method: 'updateSource',
  data: {
    id: 'some_id',
    params: {},
  }
}

preload

Videonun oynatılmasından önce önbelleğe alma işlemini başlatma yöntemi.

Örnek
{
  method: 'preload'
}

requestFullscreen

Tam ekran modunu açma yöntemi.

Örnek
{
  method: 'requestFullscreen'
}

exitFullscreen

Tam ekran modundan çıkma yöntemi.

Örnek
{
  method: 'exitFullscreen'
}

hideControls

Oynatma kontrollerinin gizlenmesi.

Örnek
{
    method: 'hideControls'
}
Komuta göre video oynatma örneği
window.addEventListener('message', function (event) {
     if (event.data.method === 'play') {
         document.getElementById('video').play();
     }
});

Cevap formatı

Komutların uygulanıp uygulanmadığına dair geri bildirim için video durumunu bildiren olayı kullanın.

Örneğin:

  • skipAd metodunu çağırırken, reklam başarıyla atlanırsa adSkip olayı oluşturulur; bir sorun oluşursa olay gönderilmez.

  • setPlaybackRate yöntemi kullanıldığında, yanıt olarak playbackRateChanged olayı tetiklenir.

Akıllı TV'de videonun doğru şekilde görüntülenebilmesi amacıyla her yöntem için bir yanıt olayının olması gerekir.

Destek Ekibi'ne yaz

Önceki
Mobil oyuncu
Sonraki
Aramada video gösterimi engelleme