Web Alıcısına Reklam Araları API'si Desteği ekleme

1. Genel Bakış

Google Cast logosu

Bu codelab'de, Cast Ad Breaks API'yi kullanan özel bir web alıcı uygulamasının nasıl oluşturulacağı açıklanmaktadır.

Google Cast nedir?

Google Cast, kullanıcıların mobil cihazdaki içerikleri TV'ye yayınlamasına olanak tanır. Kullanıcılar daha sonra mobil cihazlarını TV'de medya oynatma için uzaktan kumanda olarak kullanabilir.

Google Cast SDK, uygulamanızı genişleterek TV'yi veya ses sistemini kontrol etmenizi sağlar. Cast SDK, Google Cast Tasarım Kontrol Listesi'ne göre gerekli kullanıcı arayüzü bileşenlerini eklemenizi sağlar.

Google Cast Tasarım Kontrol Listesi, Cast uygulamalarını standartlaştırmak ve kullanıcıların desteklenen tüm platformlarda sezgisel bir deneyim yaşamasını sağlamak için hazırlanmıştır.

Ne geliştireceğiz?

Bu codelab'i tamamladığınızda Break API'den yararlanan bir Cast alıcı oluşturmuş olacaksınız.

Neler öğreneceksiniz?

  • Yayın için içerikte VMAP ve VAST araları ekleme
  • Ara kliplerini atlama
  • Sarma işleminde varsayılan ara davranışını özelleştirme

İhtiyacınız olanlar

Deneyim

Bu codelab'e devam etmeden önce aşağıdaki deneyime sahip olduğunuzdan emin olun.

  • Genel web geliştirme bilgisi.
  • Cast Web Receiver uygulamaları oluşturma

Bu eğitimi nasıl kullanacaksınız?

Yalnızca okuyun Okuyun ve alıştırmaları tamamlayın

Web uygulamaları oluşturma deneyiminizi nasıl değerlendirirsiniz?

Başlangıç Orta İleri

2. Örnek kodu alın

Tüm örnek kodu bilgisayarınıza indirin...

ve indirilen ZIP dosyasını açın.

3. Alıcıyı yerel olarak dağıtma

Web alıcınızı yayın cihazıyla kullanabilmek için web alıcınızın, yayın cihazınızın erişebileceği bir yerde barındırılması gerekir. HTTPS'yi destekleyen bir sunucunuz varsa aşağıdaki talimatları atlayın ve URL'yi not edin. Bu URL'ye sonraki bölümde ihtiyacınız olacaktır.

Kullanabileceğiniz bir sunucunuz yoksa Firebase Hosting veya ngrok'u kullanabilirsiniz.

Sunucuyu çalıştırma

Seçtiğiniz hizmeti kurduktan sonra app-start simgesine gidin ve sunucunuzu başlatın.

Barındırılan alıcınızın URL'sini not edin. Bu bilgiyi sonraki bölümde kullanacaksınız.

4. Cast Geliştirici Konsolu'nda uygulama kaydetme

Bu codelab'de oluşturulan özel alıcıyı Chromecast cihazlarda çalıştırabilmek için uygulamanızı kaydetmeniz gerekir. Uygulamanızı kaydettikten sonra, Gönderen Uygulamasının Web Alıcı uygulamasını başlatmak üzere yapılandırılması gereken bir uygulama kimliği oluşturulur.

"Yeni Uygulama Ekle" düğmesinin vurgulandığı Google Cast SDK Geliştirici Konsolu'nun resmi

"Yeni uygulama ekle"yi tıklayın.

"Yeni alıcı uygulaması" ekranının, "Özel alıcı" seçeneği vurgulanmış haldeki resmi

"Özel alıcı"yı seçin. Oluşturacağımız öğe budur.

"Alıcı Uygulaması URL'si" alanına bir URL yazan kişinin gösterildiği "Yeni Özel Alıcı" ekranının resmi

Yeni alıcınızın ayrıntılarını girin. Web alıcı uygulamanızı barındırmayı planladığınız yere yönlendiren URL'yi kullandığınızdan emin olun. Uygulamayı kaydettikten sonra konsol tarafından oluşturulan Uygulama Kimliği'ni not edin. Gönderen uygulama, sonraki bir bölümde bu tanımlayıcıyı kullanacak şekilde yapılandırılacaktır.

Ayrıca, alıcı uygulamanızı yayınlamadan önce erişebilmesi için Google Cast yayın cihazı kaydetmeniz gerekir. Alıcı uygulamanızı yayınladıktan sonra tüm Google Cast cihazlarında kullanılabilir. Bu codelab'in amaçları doğrultusunda, yayınlanmamış bir alıcı uygulamasıyla çalışmanız önerilir.

Google Cast SDK Geliştirici Konsolu'nun "Yeni Cihaz Ekle" düğmesi vurgulanmış görüntüsü

"Yeni cihaz ekle"yi tıklayın.

"Yayın alıcı cihaz ekle" iletişim kutusunun resmi

Yayın cihazınızın arkasında yazan seri numarasını girin ve cihaza açıklayıcı bir ad verin. Seri numaranızı, Google Cast SDK Geliştirici Konsolu'na erişirken ekranınızı Chrome'da yayınlayarak da bulabilirsiniz.

Alıcınızın ve cihazınızın teste hazır olması 5-15 dakika sürer. 5-15 dakika bekledikten sonra yayın cihazınızı yeniden başlatmanız gerekir.

5. Başlangıç projesini hazırlama

Bu codelab'e başlamadan önce, reklam arası API'lerine genel bir bakış sunan reklam geliştirici kılavuzunu incelemeniz faydalı olabilir.

İndirdiğiniz başlangıç uygulamasına Google Cast desteği eklenmelidir. Bu codelab'de kullanılan bazı Google Cast terimleri şunlardır:

  • Bir gönderen uygulaması mobil cihazda veya dizüstü bilgisayarda çalışıyorsa,
  • Google Cast cihazında bir alıcı uygulaması çalışıyor olmalıdır.

Artık en sevdiğiniz metin düzenleyiciyi kullanarak başlangıç projesinin üzerine yeni özellikler eklemeye hazırsınız:

  1. Örnek kod indirme işleminizden klasör simgesiapp-start dizinini seçin.
  2. js/receiver.js ve index.html dosyalarını açın.

Bu codelab'i uygularken seçtiğiniz web barındırma çözümünün yapılan değişikliklerle güncellenmesi gerektiğini unutmayın. Doğrulama ve test işlemlerine devam ederken değişiklikleri ana siteye aktardığınızdan emin olun.

Uygulama Tasarımı

Belirtildiği gibi, codelab'de Cast oturumu başlatmak için bir gönderen uygulaması, reklam arası API'lerini kullanacak şekilde değiştirilecek bir alıcı uygulaması kullanılır.

Bu codelab'de, alıcı uygulamasını başlatmak için Cast and Command Tool web göndereni olarak görev yapacak. Başlamak için aracı Chrome tarayıcısında açın. Cast SDK Developer Console'da size verilen Alıcı Uygulama Kimliği'ni girin ve gönderen uygulamasını test için yapılandırmak üzere Ayarla'yı tıklayın.

Not: Yayın simgesinin görünmediğini fark ederseniz Web Receiver'ın ve yayın cihazlarının, Cast Developer Console'da düzgün şekilde kaydedildiğinden emin olun. Henüz yapmadıysanız yeni kaydedilen tüm yayın cihazlarına güç döngüsü uygulayın.

Bu kod laboratuvarının ana odak noktası alıcı uygulamadır. Alıcı uygulama, index.html içinde tanımlanan bir ana görünüm ve js/receiver.js adlı bir JavaScript dosyasından oluşur. Bunlar aşağıda daha ayrıntılı olarak açıklanmıştır.

index.html

Bu HTML dosyası, cast-media-player öğesi tarafından sağlanan alıcı uygulamamızın kullanıcı arayüzünü içerir. Ayrıca CAF SDK'sını ve Cast Debug Logger kitaplıklarını da yükler.

receiver.js

Bu komut dosyası, alıcı uygulamamızın tüm mantığını yönetir. Şu anda, yayın bağlamını başlatmak ve başlatma sırasında bir video öğesi yüklemek için temel bir CAF alıcısı içerir. Cast ve Command aracına geri günlük kaydı sağlamak için bazı hata ayıklama günlükçüsü özellikleri de eklendi.

6. İçeriğinize VMAP ekleme

Cast Web Receiver SDK, VMAP olarak da bilinen Dijital Video Çok Reklamlı Oynatma Listeleri aracılığıyla belirtilen reklamları destekler. XML yapısı, bir medyanın reklam aralarını ve ilişkili ara klip meta verilerini belirtir. SDK, bu reklamları eklemek için MediaInformation nesnesinde vmapAdsRequest özelliğini sağlar.

js/receiver.js dosyasında bir VastAdsRequest nesnesi oluşturun. LOAD request interceptor işlevini bulun ve aşağıdaki kodla değiştirin. DoubleClick'ten örnek bir VMAP etiketi URL'si içerir ve aynı URL'ye yapılan sonraki isteklerin, henüz izlenmemiş reklam araları içeren bir XML şablonu oluşturmasını sağlamak için rastgele bir korelasyon belirleyici değeri sağlar.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');

      // Create the VMAP Ads request data and append it to the MediaInformation.
      const vmapUrl =
          'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
          Math.floor(Math.random() * Math.pow(10, 10));
      let vmapRequest = new cast.framework.messages.VastAdsRequest();
      vmapRequest.adTagUrl = vmapUrl;
      loadRequestData.media.vmapAdsRequest = vmapRequest;

      castDebugLogger.warn(
          'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);

      return loadRequestData;
    });

js/receiver.js dosyasındaki değişikliklerinizi kaydedin ve dosyayı web sunucunuza yükleyin. Yayınla simgesini tıklayarak Yayınla ve Komut Aracı'nda bir yayın oturumu başlatın. VMAP reklamları oynatılmalı, ardından ana içerik oynatılmalıdır.

7. İçeriğinize VAST ekleme

Daha önce de belirtildiği gibi, Web Alıcı SDK'sında birçok reklam türü desteklenir. Bu bölümde, VAST olarak da bilinen Dijital Video Reklam Sunma Şablonu reklamlarını entegre etmek için kullanılabilecek API'ler vurgulanmaktadır. Önceki bölümdeki VMAP kodunu uyguladıysanız kodu yorum satırı haline getirin.

Aşağıdaki kodu, yükleme isteği yakalayıcısından sonra js/receiver.js dosyanıza kopyalayın. Bu yanıt, DoubleClick'ten alınan altı VAST reklam arası klibi ve rastgele bir korelasyon değeri içerir. Bu araya girme klipleri 5 araya girme işlemine atanır. Her aranın position değeri, videodan önce gösterilen reklam (position değeri 0 olarak ayarlanır) ve videodan sonra gösterilen reklam (position değeri -1 olarak ayarlanır) araları dahil olmak üzere ana içeriğe göre saniye cinsinden bir süreye ayarlanır.

const addVASTBreaksToMedia = (mediaInformation) => {
  mediaInformation.breakClips = [
    {
      id: 'bc1',
      title: 'bc1 (Pre-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('preroll')
      }
    },
    {
      id: 'bc2',
      title: 'bc2 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc3',
      title: 'bc3 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc4',
      title: 'bc4 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc5',
      title: 'bc5 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc6',
      title: 'bc6 (Post-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('postroll')
      }
    }
  ];

  mediaInformation.breaks = [
    {id: 'b1', breakClipIds: ['bc1'], position: 0},
    {id: 'b2', breakClipIds: ['bc2'], position: 15},
    {id: 'b3', breakClipIds: ['bc3', 'bc4'], position: 60},
    {id: 'b4', breakClipIds: ['bc5'], position: 100},
    {id: 'b5', breakClipIds: ['bc6'], position: -1}
  ];
};

Not: Bir aranın breakClipIds özelliği bir dizidir. Bu nedenle, her araya birden fazla ara klibi atanabilir.

js/receiver.js file dosyanızda LOAD mesajı yakalayıcısını bulun ve aşağıdaki kodla değiştirin. VAST türü reklamları göstermek için VMAP çalışmasının yorum satırı olarak işaretlendiğini unutmayın.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');

      // Create the VMAP Ads request data and append it to the MediaInformation.
      // const vmapUrl =
      //     'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
      //     Math.floor(Math.random() * Math.pow(10, 10));
      // let vmapRequest = new cast.framework.messages.VastAdsRequest();
      // vmapRequest.adTagUrl = vmapUrl;
      // loadRequestData.media.vmapAdsRequest = vmapRequest;

      // Append VAST ad breaks to the MediaInformation.
      addVASTBreaksToMedia(loadRequestData.media);

      castDebugLogger.warn(
          'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);

      return loadRequestData;
    });

js/receiver.js dosyasındaki değişikliklerinizi kaydedin ve dosyayı web sunucunuza yükleyin. Yayınla simgesini tıklayarak Yayınla ve Komut Aracı'nda bir yayın oturumu başlatın. VAST reklamları oynatılmalı, ardından ana içerik oynatılmalıdır.

8. Reklam Arası Atlama

CAF'de, reklam davranışları için özel iş kurallarını uygulamanıza yardımcı olan BreakManager adlı bir sınıf bulunur. Bu özelliklerden biri, uygulamaların bazı koşullara bağlı olarak araları ve ara kliplerini programatik olarak atlamasına olanak tanır. Bu örnekte, içeriğin ilk 30 saniyesi içinde yer alan ancak videodan sonra gösterilen reklam araları olmayan bir reklam arasının nasıl atlanacağı gösterilmektedir. Önceki bölümde yapılandırılan VAST reklamları kullanılırken 5 ara tanımlanır: 1 videodan önce gösterilen reklam arası, 3 ara reklam (15, 60 ve 100 saniyede) ve son olarak 1 videodan sonra gösterilen reklam arası. Adımları tamamladıktan sonra yalnızca konumu 15. saniyede olan videodan önce gösterilen reklam ve ara reklam atlanır.

Bunun için uygulama, BreakManager üzerinden kullanılabilen API'leri çağırarak reklam yüklemeyi durdurmak için bir araya girici ayarlamalıdır. Örneğe referans almak için aşağıdaki satırı js/receiver.js ve playerManager değişkenlerini içeren satırlardan sonra js/receiver.js dosyanıza kopyalayın.context

const breakManager = playerManager.getBreakManager();

Uygulama, 30 saniyeden önce gerçekleşen reklam aralarını yoksayacak bir kurala sahip bir araya girme işlevi oluşturmalıdır. Bu sırada, videodan sonra gösterilen reklam aralarını (position değerleri -1 olduğundan) göz önünde bulundurmalıdır. Bu araya girme işlevi, PlayerManager üzerindeki LOAD araya girme işlevine benzer ancak bu işlev, reklam arası kliplerinin yüklenmesine özeldir. Bu ayarı LOAD isteği yakalayıcısından sonra ve addVASTBreaksToMedia işlev bildiriminden önce ayarlayın.

Aşağıdaki kodu js/receiver.js dosyasına kopyalayın.

breakManager.setBreakClipLoadInterceptor((breakClip, breakContext) => {
  /**
   * The code will skip playback of break clips if the break position is within
   * the first 30 seconds.
   */
  let breakObj = breakContext.break;
  if (breakObj.position >= 0 && breakObj.position < 30) {
    castDebugLogger.debug(
        'MyAPP.LOG',
        'Break Clip Load Interceptor skipping break with ID: ' + breakObj.id);
    return null;
  } else {
    return breakClip;
  }
});

Not: Burada null döndürülürse BreakClip işlenmez. Break öğesinde tanımlanmış ara klipleri yoksa ara atlanır.

js/receiver.js dosyasındaki değişikliklerinizi kaydedin ve dosyayı web sunucunuza yükleyin. Yayınla simgesini tıklayarak Yayınla ve Komut Aracı'nda bir yayın oturumu başlatın. VAST reklamları işlenmelidir. Videodan önce gösterilen ve ilk ara reklam (position 15 saniye olan) reklamların oynatılmadığını unutmayın.

9. Ara verme arama davranışını özelleştirme

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

Cast SDK, arama sırasında hangi araların oynatılacağını özelleştirmek için BreakManager içinde setBreakSeekInterceptor API'sini sağlar. Bir uygulama, özel mantığını bu API aracılığıyla sağladığında SDK, bir veya daha fazla ara üzerinde konumlama işlemi her gerçekleştirildiğinde bu mantığı çağırır. Geri çağırma işlevine, seekFrom konumu ile seekTo konumu arasındaki tüm araları içeren bir nesne iletilir. Uygulama daha sonra BreakSeekData değerini değiştirip döndürmelidir.

Aşağıdaki örnek, kullanımını göstermek için varsayılan davranışı geçersiz kılar. Bu örnekte, oynatılmayan tüm aralar alınır ve zaman çizelgesinde görünen ilk ara oynatılır.

Aşağıdaki kodu js/receiver.js dosyanızda setBreakClipLoadInterceptor tanımının altına kopyalayın.

breakManager.setBreakSeekInterceptor((breakSeekData) => {
  /**
   * The code will play an unwatched break between the seekFrom and seekTo
   * position. Note: If the position of a break is less than 30 then it will be
   * skipped due to the setBreakClipLoadInterceptor code.
   */
  castDebugLogger.debug(
      'MyAPP.LOG',
      'Break Seek Interceptor processing break ids ' +
          JSON.stringify(breakSeekData.breaks.map(adBreak => adBreak.id)));

  // Remove all other breaks except for the first one.
  breakSeekData.breaks.splice(1,breakSeekData.breaks.length);
  return breakSeekData;
});

Not: İşlev bir değer döndürmezse veya null döndürürse reklam arası oynatılmaz.

js/receiver.js dosyasındaki değişikliklerinizi kaydedin ve dosyayı web sunucunuza yükleyin. Yayınla simgesini tıklayarak Yayınla ve Komut Aracı'nda bir yayın oturumu başlatın. VAST reklamları işlenmelidir. Videodan önce gösterilen ve ilk ara reklam (position 15 saniye olan) reklamların oynatılmadığını unutmayın.

Reklam klibi yükleme engelleyicisi tarafından atlanan tüm araları geçmek için oynatma süresinin 30 saniyeye ulaşmasını bekleyin. Bu sınıra ulaşıldığında Medya Kontrolü sekmesine giderek arama komutu gönderin. Seek Into Media girişini 300 saniye ile doldurun ve TO düğmesini tıklayın. Break Seek Interceptor'da yazdırılan günlükleri not edin. Varsayılan davranış artık seekFrom saatine daha yakın bir zamanda reklam arası oynatılacak şekilde geçersiz kılınmalıdır.

10. Tebrikler

Artık en yeni Cast alıcı SDK'sını kullanarak alıcı uygulamanıza nasıl reklam ekleyeceğinizi biliyorsunuz.

Daha fazla bilgi için Ad Breaks Geliştirici Kılavuzu'na bakın.