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. Kullanıcılar, mobil cihazlarını TV'de medya oynatmak için uzaktan kumanda olarak kullanabilir.

Google Cast SDK'sı, uygulamanızı bir TV veya ses sistemini kontrol edecek şekilde genişletmenize olanak tanır. 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 Listesi, Cast uygulamalarını standartlaştırarak kullanıcıların tüm desteklenen platformlarda sezgisel bir deneyim yaşamasını sağlamak için sağlanmıştır.

Ne oluşturacağız?

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

Neler öğreneceksiniz?

  • Cast için içeriklere VMAP ve VAST araları ekleme
  • Ara kliplerini atlama
  • Arama sırasındaki varsayılan ara verme davranışını özelleştirme

İhtiyacınız olanlar

Deneyim

Bu kod laboratuvarına devam etmeden önce aşağıdaki deneyime sahip olduğunuzdan emin olun.

  • Genel web geliştirme bilgisi
  • Cast web alıcısı uygulamaları oluşturma.

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

Yalnızca okuyun Okuyup alıştırmaları tamamlayın

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

Acemi Orta Seviye Uzman

2. Örnek kodu alın

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

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

3. Alıcının yerel olarak dağıtılması

Web alıcınızı bir Cast cihazıyla kullanabilmek için Cast 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ıp bir sonraki bölümde ihtiyaç duyacağınız URL'yi not edin.

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

Sunucuyu çalıştırma

Tercih ettiğiniz hizmeti ayarladıktan sonra app-start bölümüne gidin ve sunucunuzu başlatın.

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

4. Cast Geliştirici Konsolu'na uygulama kaydetme

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

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

"Yeni uygulama ekle"yi tıklayın

"Özel Alıcı" seçeneğinin vurgulandığı "Yeni Alıcı Uygulaması" ekranının resmi

"Özel Alıcı"yı seçin. Şu anda bunu oluşturuyoruz.

"Alıcı Uygulaması URL'si" alanına bir kullanıcının yazdığı URL'yi gösteren "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 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 uygulaması, sonraki bir bölümde bu tanımlayıcıyı kullanacak şekilde yapılandırılır.

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

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

"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 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 Cast cihazınızı yeniden başlatmanız gerekir.

5. Başlangıç projesini hazırlama

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

Google Cast desteğinin, indirdiğiniz başlangıç uygulamasına eklenmesi gerekir. Bu codelab'de kullanılan bazı Google Cast terimleri aşağıda verilmiştir:

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

Artık favori metin düzenleyicinizi kullanarak başlangıç projesinin üzerine geliştirme yapmaya hazırsınız:

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

Bu kod laboratuvarını tamamlarken seçtiğiniz web barındırma çözümünün, yapılan değişikliklerle güncelleneceğ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 de belirtildiği gibi, kod laboratuvarının bir Cast oturumu başlatmak için bir gönderen uygulaması ve reklam arası API'lerini kullanacak şekilde değiştirilecek bir alıcı uygulaması vardır.

Bu codelab'de, alıcı uygulamasını başlatmak için Yayınlama ve Komut Aracı web göndericisi olarak kullanılır. Başlamak için aracı bir Chrome tarayıcıda açın. Gönderen uygulamasını test için yapılandırmak üzere Cast SDK Geliştirici Konsolu'nda size verilen Alıcı Uygulama Kimliği'ni girin ve Ayarla'yı tıklayın.

Not: Yayınlama simgesinin görünmediğini fark ederseniz web alıcısının ve yayın cihazlarının Cast Developer Console'a düzgün şekilde kaydedildiğinden emin olun. Henüz yapmadıysanız yeni kayıtlı tüm yayın cihazlarını kapatıp açın.

Bu kod laboratuvarının ana odak noktası alıcı uygulamasıdır. Bu 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 işleminden sonra bir video öğesi yüklemek için temel bir CAF alıcısı içerir. Yayınlama ve Komut aracına geri günlük kaydı sağlamak için bazı hata ayıklama günlük kaydı özellikleri de eklendi.

6. İçeriğinize VMAP ekleme

Cast Web Receiver SDK'sı, VMAP olarak da bilinen Dijital Video Çok Reklamlı 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 klip meta verilerini belirtir. SDK, bu reklamları eklemek için MediaInformation nesnesinde vmapAdsRequest mülkünü sağlar.

js/receiver.js dosyasında bir VastAdsRequest nesnesi oluşturun. LOAD istek engelleyici 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 ilişkilendirici 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;
    });

Değişikliklerinizi js/receiver.js dosyasına 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ıldıktan sonra ana içerik oynatılmalıdır.

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ılabilen API'ler vurgulanmaktadır. Önceki bölümdeki VMAP kodunu uyguladıysanız bu kodu yoruma alın.

Aşağıdakileri, yükleme isteği tutucudan sonra js/receiver.js dosyanıza kopyalayın. DoubleClick'ten altı VAST ara klipsi 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çerikle göreli 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: Aranın breakClipIds mülkü bir dizidir. Bu, her ara için birden fazla ara klibi atanabileceği anlamına gelir.

js/receiver.js file dosyanızda LOAD mesajı tutucusunu bulun ve aşağıdaki kodla değiştirin. VAST türü reklamları göstermek için VMAP çalışmasının yoruma alındığı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;
    });

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

8. Reklam arasını 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 bazı koşullara bağlı olarak araları programatik olarak atlamasına ve klipleri bölmelerine 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 uygulama, ara yükleme için bir müdahaleci ayarlamak üzere BreakManager üzerinden kullanılabilen API'leri çağırmalıdır. Örneğe referans almak için aşağıdaki satırı, context ve playerManager değişkenlerini içeren satırlardan sonra js/receiver.js dosyanıza kopyalayın.

const breakManager = playerManager.getBreakManager();

Uygulama, 30 saniyeden önce gerçekleşen reklam aralarını yok sayma kuralına sahip bir müdahaleci ayarlamalıdır. Bu müdahaleci, position değerleri -1 olduğu için videodan sonra gösterilen araları da dikkate alır. Bu müdahaleci, PlayerManager'deki LOAD müdahalecisinin işleyişine benzer ancak reklam arası kliplerinin yüklenmesine özeldir. Bunu, LOAD isteği önleyicisinden sonra ve addVASTBreaksToMedia işlev bildiriminden önce ayarlayın.

Aşağıdakileri 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üldüğünde BreakClip işlenmez. Bir Break için tanımlanmış ara klip yoksa ara atlanır.

Değişikliklerinizi js/receiver.js dosyasına 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 işlenmelidir. Videodan önce gösterilen ve ilk videonun ortasında gösterilen (position değeri 15 saniye olan) reklamların oynatılmadığını unutmayın.

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

Geçmiş aralara göz atarken 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 ayarlanmış Break'i oynatır. Ardından, bu aranın isWatched mülkü 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'sı, BreakManager'da setBreakSeekInterceptor API'sini sağlayarak hangi araların oynatılacağını özelleştirmenize olanak tanır. Bir uygulama bu API aracılığıyla özel mantığını sağladığında SDK, bir veya daha fazla ara sırasında bir arama 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. Ardından uygulamanın BreakSeekData öğesini değiştirip döndürmesi gerekir.

Kullanımını göstermek için aşağıdaki örnekte, istenilen tüm araları atlayıp yalnızca zaman çizelgesinde görünen ilk aralığı oynatarak varsayılan davranış geçersiz kılınır.

Aşağıdakileri js/receiver.js dosyanıza, 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 ara verilmez.

Değişikliklerinizi js/receiver.js dosyasına 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 işlenmesi gerekir. Videodan önce gösterilen ve ilk videonun ortasında gösterilen (position değeri 15 saniye olan) reklamların oynatılmadığını unutmayın.

Ara klip yükleme engelleyicisi tarafından atlanan tüm araları atlamak için oynatma süresinin 30 saniyeye ulaşmasını bekleyin. İstediğiniz konuma ulaştı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 son Cast Receiver 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.