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 Web Alıcı uygulamasının nasıl oluşturulacağı özetlenmektedir.

Google Cast nedir?

Google Cast, kullanıcıların mobil cihazdan TV'ye içerik yayınlamasına olanak tanır. Böylece kullanıcılar, TV'de medya oynatmak için mobil cihazlarını uzaktan kumanda olarak kullanabilir.

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

Google Cast Tasarım Kontrol Listesi, desteklenen tüm platformlarda kullanıcı deneyimlerini sezgisel hale getirmek için Cast uygulamalarını standartlaştırmak amacıyla sağlanmıştır.

Ne oluşturacağız?

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

Neler öğreneceksiniz?

  • Cast için içeriğe VMAP ve VAST araları ekleme
  • Ara klipleri atlama
  • Aramada 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.

  • Web geliştirmeyle ilgili genel bilgi.
  • Cast Web Alıcı uygulamaları oluşturma.

Bu eğiticiden nasıl yararlanacaksınız?

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

Web uygulamaları geliştirme deneyiminizi nasıl değerlendirirsiniz?

Acemi Orta Yeterli

2. Örnek kodu alın

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

ve indirilen zip dosyasının paketini açın.

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

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

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

Sunucuyu çalıştırma

İstediğiniz hizmeti ayarladıktan sonra app-start bölümüne gidip sunucunuzu başlatın.

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

4. Cast Developer Console'a bir uygulama kaydetme

Chromecast cihazlarda bu codelab'de yerleşik olarak bulunan özel alıcı çalıştırabilmek için uygulamanızı kaydetmeniz gerekir. Uygulamanızı kaydettikten sonra, Web Receiver uygulamasını başlatmak için Gönderen Uygulaması'nın yapılandırılması gereken bir uygulama kimliği oluşturulur.

"Yeni Uygulama Ekle" seçeneğinin gösterildiği Google Cast SDK Developer Console'un resmi düğme vurgulanmış

"Yeni uygulama ekle"yi tıklayın

'Yeni Alıcı Uygulaması'nın resmi 'Özel Alıcı' ekranıyla seçenek vurgulanmış

"Özel Alıcı"yı seçin, oluşturduğumuz şey bu.

"Yeni Özel Alıcı"nın resmi 'Alıcı Uygulama URL'si' alanına bir kişinin yazdığı URL'yi gösteren ekran alan

Yeni alıcınızla ilgili bilgileri girin. Web Alıcı uygulamanızı barındırmayı planladığınız yeri gösteren URL'yi kullandığınızdan emin olun. Uygulamayı kaydettikten sonra konsol tarafından oluşturulan uygulama kimliğini not edin. Gönderen uygulama, daha sonraki bir bölümde bu tanımlayıcıyı kullanacak şekilde yapılandırılır.

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

"Yeni Cihaz Ekle" seçeneğinin gösterildiği Google Cast SDK'sı Developer Console'un resmi düğme vurgulanmış

"Yeni Cihaz ekle"yi tıklayın

'Yayın Alıcı Cihazı Ekle'nin resmi iletişim kutusu

Yayın cihazınızın arkasında basılı olan seri numarasını girin ve açıklayıcı bir ad verin. Seri numaranızı, Google Cast SDK Geliştirici Konsolu'na erişirken Chrome'da ekranınızı 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. Start Projesini Hazırlama

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

İndirdiğiniz başlangıç uygulamasına Google Cast desteğinin eklenmesi gerekiyor. Bu codelab'de kullanılan bazı Google Cast terminolojisi şu şekildedir:

  • Mobil cihazda veya dizüstü bilgisayarda çalışan gönderen uygulaması,
  • Google Cast cihazında çalışan bir alıcı uygulaması.

Favori metin düzenleyicinizi kullanarak başlangıç projesinin temelini oluşturmaya artık hazırsınız:

  1. İndirilen örnek koddan klasör simgesiapp-start dizinini seçin.
  2. js/receiver.js ve index.html dosyasını açın

Bu codelab üzerinde çalışırken seçtiğiniz web barındırma çözümünün yapılan değişikliklerle güncellenmesi gerektiğini unutmayın. Değişiklikleri doğrulamaya ve test etmeye devam ederken değişiklikleri ana makine sitesine aktardığınızdan emin olun.

Uygulama Tasarımı

Daha önce belirtildiği gibi codelab'de, Yayınlama Oturumu başlatmak için bir gönderen uygulaması ve reklam arası API'lerini kullanacak şekilde değiştirilecek bir alıcı uygulaması kullanılır.

Bu codelab'de Yayınlama ve Komut Aracı, alıcı uygulamayı başlatmak için web göndericisi görevi görür. Başlamak için aracı bir Chrome tarayıcıda açın. Cast SDK'sı Geliştirici Konsolu'nda 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 Alıcısı ve yayın cihazlarının Cast Developer Console'a düzgün şekilde kaydedildiğinden emin olun. Henüz yapmadıysanız az önce kaydedilmiş tüm yayın cihazlarını kapatıp açın.

Alıcı uygulama, bu codelab'in ana odak noktasıdır. index.html içinde tanımlanmış 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ı, alıcı uygulamamızın cast-media-player öğesi tarafından sağlanan kullanıcı arayüzünü içerir. Ayrıca CAF SDK'sını ve Cast Hata Ayıklama Günlükçü kitaplıklarını yükler.

receiver.js

Bu komut dosyası, alıcı uygulamamızın tüm mantığını yönetir. Şu anda yayınlama bağlamını başlatmak ve başlatmadan sonra bir video öğesi yüklemek için temel bir CAF alıcısı içeriyor. Yayınla ve Komut aracına geri kayıt yapılabilmesi için bazı hata ayıklama günlük kaydı özellikleri de eklenmiştir.

6. İçeriğinize VMAP Ekleme

Cast Web Alıcı SDK'sı, VMAP olarak da bilinen Dijital Video Çoklu Reklam Oynatma Listeleri aracılığıyla belirtilen reklamlar için destek sağlar. XML yapısı, bir medyanın reklam aralarını ve ilişkili ara klibi meta verilerini belirtir. SDK, bu reklamların eklenmesi için MediaInformation nesnesinde vmapAdsRequest özelliğini sağlar.

js/receiver.js dosyasında VastAdsRequest nesnesi oluşturun. LOAD istek müdahalesi işlevini bulun ve aşağıdaki kodla değiştirin. DoubleClick'ten örnek bir VMAP etiket 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 correlator 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ında yaptığınız değişiklikleri kaydedin ve dosyayı web sunucunuza yükleyin. Yayınla ve Komut Aracı'nda Yayınla simgesini tıklayarak bir Cast oturumu başlatın. VMAP reklamları oynatılmalı ve ardından ana içerik devam etmelidir.

7. İçeriğinize VAST Ekleme

Daha önce belirtildiği gibi, Web Receiver SDK'da birçok reklam türü için destek mevcuttur. Bu bölümde, VAST olarak da bilinen Dijital Video Reklam Sunma Şablonu reklamlarını entegre etmek için kullanılabilecek API'ler açıklanmaktadır. Önceki bölümde yer alan VMAP kodunu uyguladıysanız açıklama ekleyin.

Yükleme isteği önleyicisinden sonra aşağıdakileri js/receiver.js dosyanıza kopyalayın. Bu dosya, DoubleClick'ten altı VAST ara klibi ve rastgele bir correlator değeri içerir. Bu ara klipleri 5 araya atanmıştır. Her aranın position değeri, videodan önce gösterilen reklam (position 0 olarak ayarlandı) ve videodan sonra gösterilen reklam (position -1 olarak ayarlandı) aralar dahil olmak üzere ana içeriğe kıyasla saniye cinsinden bir süreye ayarlandı.

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: Araların breakClipIds özelliği bir dizidir. Diğer bir deyişle, her araya birden fazla ara klibi atanabilir.

js/receiver.js file içinde LOAD mesajı müdahalecisini bulun ve aşağıdaki kodla değiştirin. VMAP çalışmasının, VAST türü reklamları göstermek için yorumlandığını 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ında yaptığınız değişiklikleri kaydedin ve dosyayı web sunucunuza yükleyin. Yayınla ve Komut Aracı'nda Yayınla simgesini tıklayarak bir Cast oturumu başlatın. VAST reklamları oynatılmalı ve ardından ana içerik izlenmelidir.

8. Reklam Arası Atlama

CAF'de, reklam davranışları için özel iş kuralları uygulamanıza yardımcı olan BreakManager adlı bir sınıf bulunur. Bu özelliklerden biri, uygulamaların belirli bir koşula göre programlı olarak araları atlamasına ve klipleri bölmesine olanak tanır. Bu örnekte, konumu içeriğin ilk 30 saniyesinde olan, ancak videodan sonra gösterilen reklam araları dışında olan 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ımlanmıştır: 1 videodan önce gösterilen reklam arası, 3 videonun ortasında gösterilen reklam arası (15, 60 ve 100. saniyede) ve son olarak bir videodan sonra gösterilen reklam arası. Adımlar tamamlandıktan sonra yalnızca konumu 15 saniye olan videodan önce gösterilen reklam ve videonun ortasında gösterilen reklam atlanır.

Bunun için uygulamanın, ara yüklemeye yönelik bir müdahaleci ayarlamak amacıyla BreakManager üzerinden kullanılabilen API'leri çağırması gerekir. Örneğe referans vermek için aşağıdaki satırı js/receiver.js dosyanıza, context ve playerManager değişkenlerini içeren satırlardan sonra kopyalayın.

const breakManager = playerManager.getBreakManager();

Uygulama, 30 saniyeden önce gerçekleşen reklam aralarını yoksayacak ve videodan sonra gösterilen reklam aralarını da göz önünde bulunduracak bir kural içeren bir önleyici ayarlamalıdır (position değerleri -1 olduğundan). Bu önleyici, PlayerManager üzerindeki YÜK önleyicisi gibi çalışır ancak ara kliplerinin yüklenmesine özeldir. Bunu, LOAD isteği önleyicisinden sonra ve addVASTBreaksToMedia işlev bildiriminden önce ayarlayın.

Aşağıdaki komutu 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: null buraya döndürüldüğünde, işlenmekte olan BreakClip atlanır. Break için tanımlanmış herhangi bir ara klibi yoksa aranın kendisi atlanır.

js/receiver.js dosyasında yaptığınız değişiklikleri kaydedin ve dosyayı web sunucunuza yükleyin. Yayınla ve Komut Aracı'nda Yayınla simgesini tıklayarak bir Cast oturumu başlatın. VAST reklamlarının işlenmesi gerekir. Videodan önce gösterilen reklam ve videonun ortasında gösterilen ilk reklam (position değeri 15 saniye olan) reklamların oynatılmadığını unutmayın.

9. Ara Arama Davranışını Özelleştirme

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

Cast SDK, bir aramada hangi araların oynatılacağını özelleştirmek için BreakManager ürününde setBreakSeekInterceptor API'sini sağlar. Bir uygulama kendi özel mantığını bu API aracılığıyla sağladığında SDK, bir veya daha fazla aranın sonunda bir arama işlemi gerçekleştirildiğinde uygulamayı çağırır. Geri çağırma işlevine, seekFrom konumu ile seekTo konumu arasındaki tüm araları içeren bir nesne iletilir. Daha sonra uygulamanın BreakSeekData öğesini değiştirmesi ve geri göndermesi gerekir.

Kullanım durumunu göstermek için aşağıdaki örnek, aranan tüm araları alıp zaman çizelgesinde görünen ilk arayı oynatarak varsayılan davranışı geçersiz kılar.

Aşağıdakini, setBreakClipLoadInterceptor tanımının altındaki js/receiver.js dosyanıza 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 değerini döndürürse hiçbir ara oynatılmaz.

js/receiver.js dosyasında yaptığınız değişiklikleri kaydedin ve dosyayı web sunucunuza yükleyin. Yayınla ve Komut Aracı'nda Yayınla simgesini tıklayarak bir Cast oturumu başlatın. VAST reklamlarının işlenmesi gerekir. Videodan önce gösterilen reklam ve videonun ortasında gösterilen ilk reklam (position değeri 15 saniye olan) reklamların oynatılmadığını unutmayın.

Ara klibi yükleme önleyicisi tarafından atlanan tüm araları geçmek için oynatma süresinin 30 saniyeye ulaşmasını bekleyin. Sınıra ulaşıldıktan sonra Medya Kontrolü sekmesine giderek bir arama komutu gönderin. Seek Into Media (Medyaya Ara) girişini 300 saniyeyle doldurun ve BİTİŞ düğmesini tıklayın. Break Seek Interceptor'da yazdırılan günlükleri not edin. seekFrom saatine yakın aranın oynatılması için varsayılan davranış artık 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 Reklam Araları Geliştirici Kılavuzu'na bakın.